AI Glot websiteOpen AI Glot
REST APIErrori

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.

Esempio di errore
{
  "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

StatoSignificatoCosa fare
400Richiesta malformata o campo sconosciutoCorreggi la richiesta
401Credenziale mancante, non valida, scaduta o revocataSostituiscila o rinnovala
403Autenticazione riuscita, ma accesso non consentitoConcedi lo scope o la funzionalità richiesta
404Risorsa assente o non appartenente a questo workspaceControlla l’ID e il workspace
409Lo stato corrente è in conflitto con la richiestaLeggi la risorsa, poi decidi
413Corpo della richiesta troppo grandeInvia un corpo più piccolo
422Valore ben formato, ma non validoCorreggi il valore indicato
429Limite di richieste raggiuntoAttendi Retry-After
500/503AI Glot ha riscontrato un errore o è temporaneamente non disponibileRiprova 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:

JSON
"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.

Use these docs with your AI tools

An AI agent can read this documentation directly. You do not need an account or an API key. Everything here is public and read-only.

Query these docs via MCP

Recommended

Add this server to Claude, Claude Code, Cursor, Mistral, or any tool that supports MCP. Your agent can then search AI Glot Docs documentation and read it in full, instead of answering from memory.

https://ai-glot.com/docs/mcp
  • searchFind the passages that answer a question.
  • fetchRead one page in full, as Markdown.
  • list_pagesSee every page in this documentation.

Query these docs over HTTP

The same tools also work as plain web requests. Use this for scripts, or for any tool that does not support MCP. There is one endpoint per tool. Arguments go in the query string, and the answer comes back as JSON.

https://ai-glot.com/docs/api/docs/search?query=custom+domain

Read the OpenAPI description. It is built from the same definitions as the tools, so it always matches what the endpoints do.

Read these docs as Markdown

Add .md to any page URL to get its Markdown source. You can also send the headerAccept: text/markdown to the page URL itself.

To read the whole documentation in one file, open llms-full.txt. For a short index of every page, open llms.txt.