Errori
Gestisci gli errori dell’API AI Glot con codici stabili, ID delle richieste, indicazioni sui nuovi tentativi e spiegazioni con link interni per ogni errore documentato.
Tutti gli errori dell’API usano lo stesso formato. Usa error.code per gestirli, mai il messaggio leggibile.
{
"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
| Stato | Significato | Cosa fare |
|---|---|---|
| 400 | Richiesta malformata o campo sconosciuto | Correggi la richiesta |
| 401 | Credenziale mancante, non valida, scaduta o revocata | Sostituiscila o rinnovala |
| 403 | Autenticazione riuscita, ma accesso non consentito | Concedi lo scope o la funzionalità richiesta |
| 404 | Risorsa assente o non appartenente a questo workspace | Controlla l’ID e il workspace |
| 409 | Lo stato corrente è in conflitto con la richiesta | Leggi la risorsa, poi decidi |
| 413 | Corpo della richiesta troppo grande | Invia un corpo più piccolo |
| 422 | Valore ben formato, ma non valido | Correggi il valore indicato |
| 429 | Limite di richieste raggiunto | Attendi Retry-After |
| 500/503 | AI Glot ha riscontrato un errore o è temporaneamente non disponibile | Riprova aumentando gradualmente l’intervallo |
Codici di autenticazione e autorizzazione
authentication_required
Non è stata inviata alcuna credenziale bearer. 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 scadenza configurata. Creane o usane una sostitutiva.
api_key_revoked
Un amministratore ha revocato o sostituito questa chiave. Aggiorna l’integrazione con una credenziale attiva.
insufficient_scope
La credenziale è stata autenticata, ma non dispone dello scope richiesto per questa operazione.
feature_not_available
Il piano del workspace o la versione attuale della piattaforma non include la funzionalità richiesta.
admin_required
Solo un amministratore del workspace può eseguire l’operazione.
Codici di richiesta
invalid_request
Non è possibile analizzare la richiesta oppure questa non corrisponde al contratto dell’endpoint.
unknown_field
Una proprietà del corpo JSON non è riconosciuta. Correggi l’ortografia invece di rimuovere la convalida. I parametri query non riconosciuti non generano mai questo errore: vengono ignorati. Di conseguenza, un filtro scritto in modo errato restituisce un 200 senza filtri.
invalid_parameter
Un parametro ha tipo, intervallo o formato errato.
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 dell’endpoint.
Codici di risorsa e stato
batch_not_found
Nessuna traduzione visibile ha questo ID. Le risorse appartenenti a un altro workspace restituiscono intenzionalmente lo stesso errore.
glossary_not_found
Non esiste un glossario per questa combinazione linguistica.
resource_not_found
La risorsa o la route richiesta non esiste.
glossary_already_exists
Esiste già un glossario per questa combinazione linguistica. Aggiornalo invece di crearne un altro.
result_not_ready
La traduzione non è ancora terminata, quindi non è ancora possibile scaricare il risultato.
batch_not_editable
Lo stato attuale della traduzione non consente la modifica di gestione richiesta.
idempotency_key_reused
La Idempotency-Key è già stata usata per un’altra richiesta (altro file, nome o istruzione). Invia la stessa richiesta per ripeterla, oppure una nuova chiave per un nuovo lavoro. Vedi Creare una traduzione.
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 completo dei formati e delle relative estensioni.
file_too_large
Il file supera il limite previsto per il suo formato. I limiti variano in base al formato, non sono un limite unico (60 MB per CSV, 4 MB per un catalogo PO): una dimensione accettata per un’estensione può essere rifiutata per un’altra.
file_fetch_failed
Non è stato possibile recuperare file_url. L’URL deve usare HTTPS e puntare alla destinazione finale: i reindirizzamenti non vengono seguiti, quindi un link abbreviato o firmato che poi reindirizza non funziona.
file_retention_expired
Il periodo di conservazione del file caricato è terminato e il file non è più archiviato. Crea di nuovo la traduzione a partire dal file sorgente.
file_expired
Il file alla base di questa traduzione non è più disponibile, quindi non è possibile procedere.
result_too_large
La traduzione completata supera la dimensione massima consentita per la restituzione. Dividi il file sorgente e traducilo in più parti.
Codici di piano e approvazione
plan_invalid
Non è stato possibile trasformare l’istruzione o la richiesta di revisione in un piano utilizzabile. Non è stato addebitato nulla. Se la causa è nota, il messaggio la specifica: nel file non corrispondeva nulla all’istruzione, l’istruzione richiede di scrivere in una parte del file non adatta, oppure questa volta non è stato possibile generare il piano (invia di nuovo la stessa istruzione). Negli altri casi, riformulala: indicare i campi o le colonne da tradurre è più affidabile che descriverli.
plan_changed
expected_plan_revision inviato non corrisponde al piano attualmente disponibile per la revisione, oppure non è possibile verificare quella revisione. Questa approvazione non ha avviato nuove attività. Rileggi il batch, controlla l’ambito corrente, le esclusioni e il costo calcolato, quindi decidi se approvare usando la nuova revisione. Non ripetere alla cieca la vecchia approvazione.
no_plan_yet
È stata richiesta l’approvazione prima che esistesse un piano. Chiama prima POST /v1/batches/{batch_id}/plan: questo controllo impedisce a un’integrazione di addebitare un workspace per una traduzione che nessuno ha descritto.
batch_not_awaiting_approval
La traduzione non si trova in uno stato che consente l’approvazione; di solito è già in corso o completata. Interroga GET /v1/batches/{batch_id} invece di approvarla di nuovo.
insufficient_credits
Il saldo del workspace non è sufficiente a coprire il costo calcolato del piano (HTTP 402). Non viene prenotato nulla, quindi sarà possibile approvare la traduzione dopo aver aggiunto crediti.
L’errore include un oggetto payment, sia nell’API REST sia nello strumento MCP approve_translation:
"payment": {
"credits_needed": 30000,
"credit_balance": 5000,
"credits_missing": 25000,
"credits_to_buy": 25000,
"price_eur": 25,
"payment_url": "https://app.ai-glot.com/w/<workspace_id>/new?continue=<batch_id>&pay=1",
"plans": [
{ "plan": "Starter", "eur_per_month": 42, "credits_per_month": 100000 },
{ "plan": "Pro", "eur_per_month": 199, "credits_per_month": 1000000 }
]
}credits_to_buy indica l’acquisto minimo necessario per coprire la differenza (si applica l’importo minimo acquistabile). payment_url apre questa traduzione in AI Glot con la finestra di acquisto già aperta: mostra l’importo esatto, i pacchetti di crediti e i piani, oltre al campione gratuito se il workspace ne ha diritto. Il link funziona solo per un membro che ha effettuato l’accesso al workspace, quindi è sicuro da condividere. plans elenca i piani mensili, che offrono un costo per credito inferiore a chi traduce regolarmente; nella stessa pagina sono mostrati sotto l’acquisto una tantum.
Un agente deve chiedere all’utente prima di proporgli il link, non deve mai pagare per suo conto e, dopo il pagamento, deve controllare il saldo con GET /v1/account e approvare di nuovo dopo la conferma dell’utente. L’utente può anche avviare la traduzione da quella pagina.
Codici di lingua e glossario
language_not_supported
Il tag non rientra nel catalogo supportato. Consulta GET /v1/languages.
invalid_language_pair
Non è possibile suddividere l’identificatore della combinazione linguistica in due tag BCP 47 supportati.
glossary_term_limit_reached
Il numero di termini risultante supererebbe il limite previsto dal piano del workspace. L’aggiornamento è atomico: non è stata apportata alcuna modifica.
glossary_limit_reached
Il workspace ha raggiunto il numero massimo di glossari previsto dal piano attuale.
invalid_glossary_terms
Una o più voci del glossario sono vuote, incomplete o comunque non valide.
Codici di servizio
rate_limited
La credenziale ha superato il limite previsto per un intervallo. Attendi Retry-After, poi riprova con un jitter.
internal_error
AI Glot ha riscontrato un errore imprevisto. Riprova aumentando gradualmente l’intervallo e conserva request_id.
service_unavailable
Un servizio necessario è temporaneamente non disponibile. Riprova aumentando gradualmente l’intervallo.