---
title: "Errori"
description: "Gestisci i fallimenti delle API di AI Glot utilizzando codici di errore stabili, ID richiesta."
canonical: "https://ai-glot.com/docs/it/api/errors"
updated: "2026-08-12"
---

# Errori

Ogni fallimento dell'API utilizza un unico involucro. Effettua il branching su `error.code`, mai sul messaggio leggibile dall'utente.

```json title="Esempio di errore"
{
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "Questa credenziale non dispone dello scope batches:write.",
    "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     | Autenticato ma non autorizzato                                       | Concedi lo scope o la funzionalità richiesta |
| 404     | Risorsa assente o fuori da questo workspace                          | Verifica l'ID e il workspace                 |
| 409     | Lo stato attuale confligge 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 frequenza superato                                         | Attendi l'indicazione di `Retry-After`       |
| 500/503 | AI Glot ha riscontrato un errore o non è temporaneamente disponibile | Riprova con backoff                          |

**Correggere prima di riprovare**

La maggior parte delle risposte 400, 401, 403, 404, 409, 413 e 422 richiede una modifica della credenziale, dell'identificatore, dello stato o della richiesta.

**Riprovare in sicurezza**

Riprova l'errore 429 dopo l'intervallo `Retry-After`; riprova i codici 500 e 503 con backoff esponenziale e jitter casuale.

> **Note**
>
> Conserva il `request_id` nei log e nei messaggi di supporto. Identifica la richiesta lato server senza esporre la tua chiave API o il contenuto dei file CSV.

## Codici di autenticazione e permessi

### authentication\_required

Nessuna credenziale bearer è stata inviata. Aggiungi l'header `Authorization`.

### invalid\_api\_key

La chiave è malformata o sconosciuta. Verifica che l'intero valore `aig_live_…` sia stato copiato.

### api\_key\_expired

La chiave ha raggiunto la data di scadenza configurata. Crea o utilizza una sostitutiva.

### 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 attuale della piattaforma non includono la funzionalità richiesta.

### admin\_required

Solo un amministratore del workspace può eseguire l'operazione.

## Codici di richiesta

### invalid\_request

La richiesta non può essere analizzata o non corrisponde al contratto dell'endpoint.

### unknown\_field

Una proprietà del corpo JSON non è riconosciuta. Correggi l'ortografia invece di rimuovere la validazione. I parametri di _query_ non riconosciuti non producono mai questo errore; vengono ignorati, quindi un filtro scritto erroneamente restituirà un risultato `200` non filtrato.

### invalid\_parameter

Un parametro ha un tipo, un intervallo o un formato errato.

### invalid\_cursor

Il cursore di paginazione non è valido. Riusa `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 possiede quell'ID. Le risorse in un altro workspace restituiscono intenzionalmente lo stesso errore.

### glossary\_not\_found

Non esiste alcun glossario per quella coppia linguistica.

### resource\_not\_found

La risorsa o l'indirizzo richiesto non esiste.

### glossary\_already\_exists

Esiste già un glossario per questa coppia linguistica. Aggiornalo invece di crearne un altro.

### result\_not\_ready

La traduzione non è stata completata, quindi il risultato non può ancora essere scaricato.

### batch\_not\_editable

Lo stato attuale della traduzione non consente la modifica di manutenzione richiesta.

## Codici lingua e glossario

### language\_not\_supported

Il tag non è presente nel catalogo supportato. Consulta [`GET /v1/languages`](/docs/api/languages/list).

### invalid\_language\_pair

L'identificatore della coppia linguistica non può essere suddiviso 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; nulla è stato modificato.

### glossary\_limit\_reached

Il workspace ha raggiunto il numero massimo di glossari previsti per il piano corrente.

### invalid\_glossary\_terms

Una o più voci del glossario sono vuote, incomplete o altrimenti non valide.

## Codici di servizio

### rate\_limited

La credenziale ha superato la finestra di frequenza. Attendi `Retry-After`, quindi riprova con jitter.

### internal\_error

AI Glot ha riscontrato un errore imprevisto. Riprova con backoff e conserva il `request_id`.

### service\_unavailable

Un servizio richiesto è temporaneamente non disponibile. Riprova con backoff.