Errori

Ogni errore dell’API utilizza la stessa struttura di risposta. Esegui il branching su error.code, mai sul messaggio leggibile per l’utente.

{
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "This credential is missing the batches:write scope.",
    "docs_url": "https://ai-glot.com/docs/api/errors#insufficient_scope"
  },
  "request_id": "req_example"
}

Codici di stato

Codici di autenticazione e autorizzazione

authentication_required

Nessuna credenziale bearer inviata. Aggiungi l’header Authorization.

invalid_api_key

La chiave è malformata o sconosciuta. Verifica di aver copiato l’intero valore aig_live_….

api_key_expired

La chiave ha raggiunto la data di scadenza configurata. Creane una nuova o usane un’altra valida.

api_key_revoked

Un amministratore ha revocato o ruotato questa chiave. Aggiorna l’integrazione con una credenziale attiva.

insufficient_scope

La credenziale è autenticata ma non dispone dello scope richiesto per questa operazione.

feature_not_available

Il piano del workspace o la versione corrente della piattaforma non include la funzionalità richiesta.

admin_required

Solo un amministratore del workspace può eseguire questa operazione.

Codici di richiesta

invalid_request

Impossibile analizzare la richiesta oppure non conforme al contratto dell’endpoint.

unknown_field

Una proprietà del corpo JSON non è riconosciuta. Correggi la digitazione invece di rimuovere la convalida. I parametri query non riconosciuti non generano mai questo errore: vengono ignorati, quindi un filtro digitato male restituirà semplicemente un 200 non filtrato.

invalid_parameter

Un parametro presenta tipo, intervallo o formato errati.

invalid_cursor

Il cursore di paginazione non è valido. Riutilizza next_cursor esattamente come restituito.

request_too_large

Il corpo della richiesta supera il limite massimo consentito dall’endpoint.

Codici di risorsa e stato

batch_not_found

Nessuna traduzione visibile corrisponde a questo ID. Le risorse che si trovano in un altro workspace restituiscono intenzionalmente lo stesso errore.

glossary_not_found

Non esiste alcun glossario per questa coppia linguistica.

resource_not_found

La risorsa o la route richiesta non esiste.

glossary_already_exists

Esiste già un glossario per questa coppia linguistica. Aggiorna quello esistente anziché crearne un altro.

result_not_ready

La traduzione non è ancora completata, pertanto non è possibile scaricare il risultato.

batch_not_editable

Lo stato attuale della traduzione non consente la modifica richiesta.

Codici di file e formato

unsupported_format

L’estensione del file non è tra quelle accettate da AI Glot. Consulta File e formati per l’elenco delle dodici famiglie e delle relative estensioni.

file_too_large

Il file supera la dimensione massima prevista per il suo formato. I limiti sono definiti per singolo formato e non a livello globale (60 MB per un CSV, 4 MB per un catalogo PO), quindi una dimensione accettata per un’estensione potrebbe essere rifiutata per un’altra.

file_fetch_failed

Impossibile recuperare file_url. L’URL deve essere in HTTPS e deve puntare alla destinazione finale: i reindirizzamenti non vengono seguiti, pertanto un link accorciato o firmato con redirect fallirà in questo passaggio.

file_retention_expired

Il file caricato ha superato il periodo di conservazione e non è più archiviato. Avvia nuovamente la traduzione partendo dal file di origine.

file_expired

Il file associato a questa traduzione non è più disponibile, quindi non è possibile procedere con l’operazione.

result_too_large

La traduzione completata supera le dimensioni massime restituibili. Suddividi il file sorgente e traducilo in più parti.

Codici di piano e approvazione

plan_invalid

Impossibile convertire l’istruzione o il perfezionamento in un piano utilizzabile. Prova a riformulare: indicare esplicitamente i nomi dei campi o delle colonne da tradurre è più affidabile che descriverli a parole.

no_plan_yet

È stata tentata l’approvazione prima che fosse generato un piano. Chiama prima POST /v1/batches/{batch_id}/plan; questo controllo impedisce a un’integrazione di addebitare a un workspace una traduzione che nessuno ha impostato.

batch_not_awaiting_approval

La traduzione non si trova in uno stato in cui è possibile l’approvazione; di solito è già in esecuzione o già completata. Esegui il polling con GET /v1/batches/{batch_id} invece di inviare nuovamente l’approvazione.

insufficient_credits

Il saldo del workspace non è sufficiente a coprire il costo stimato dal piano. Nessun credito viene riservato, quindi la traduzione rimarrà approvabile non appena verranno aggiunti crediti.

Codici di lingua e glossario

language_not_supported

Il tag non rientra nel catalogo delle lingue supportate. Consulta GET /v1/languages.

invalid_language_pair

Impossibile suddividere l’identificatore della coppia linguistica in due tag BCP 47 supportati.

glossary_term_limit_reached

Il numero finale di termini supererebbe la soglia consentita dal piano del workspace. L’aggiornamento è atomico: nessuna modifica è stata applicata.

glossary_limit_reached

Il workspace ha raggiunto il numero massimo di glossari consentito per il piano attuale.

invalid_glossary_terms

Una o più voci del glossario risultano vuote, incomplete o comunque non valide.

Codici di servizio

rate_limited

La credenziale ha superato la finestra di frequenza delle richieste. Attendi il valore indicato in Retry-After, quindi riprova applicando del jitter.

internal_error

Si è verificato un errore imprevisto su AI Glot. Riprova con backoff esponenziale e conserva il request_id.

service_unavailable

Un servizio necessario è temporaneamente non disponibile. Riprova con backoff esponenziale.