Codici di errore e risoluzione dei problemi

Individuare cosa è fallito

1. Registra lo stato HTTP effettivo, il metodo e il percorso della richiesta. Stato HTTP e codice di errore applicativo descrivono livelli diversi: non sostituirli l’uno con l’altro.
2. Leggi i campi di errore secondo il protocollo chiamato. Le risposte native, OpenAI, Claude e Gemini non hanno tutte la stessa struttura.
3. Per richieste in streaming, controlla anche eventi di errore e stato di completamento; per processi asincroni, verifica il status. HTTP 200 non garantisce una generazione riuscita.
4. Usa la tabella seguente per correggere la richiesta o decidere se riprovare. message è testo esplicativo, non un enum stabile: non basare le diramazioni sulla sua formulazione.

Enumerazione dei codici di errore della piattaforma

Questa è l’enumerazione completa dei codici di errore applicativi della piattaforma. I nomi sono etichette di riferimento; i valori code nelle risposte sono numeri. “HTTP comune” è una guida diagnostica, non una corrispondenza fissa per ogni endpoint. Usa stato HTTP e corpo della risposta effettivi. Un code inoltrato dal fornitore può non appartenere a questo enum.

Il solo HTTP 429 non distingue in modo affidabile limiti di frequenza e di concorrenza. Distinguili solo quando è disponibile un codice numerico esplicito. Controlla gli identificatori nell’elenco dei modelli; non riscrivere autonomamente i valori di model.

Leggere gli errori per protocollo

Gli esempi seguenti mostrano strutture comuni generate dalla piattaforma, non un formato unico garantito per ogni errore. Errori di autenticazione possono provenire da livelli di elaborazione diversi e risposte inoltrate dal fornitore possono mantenere proprie strutture, codici stringa o tipi. Identifica la struttura effettiva prima del parsing. Se non è riconosciuta, conserva campi originali e stato HTTP invece di forzare una conversione.

API native della piattaforma

Normalmente leggi error.code e error.message. requestId può essere assente.

{
  "success": false,
  "error": {
    "code": 10000,
    "message": "Bad request"
  },
  "requestId": "req_example"
}

Alcuni errori possono usare code e message di primo livello. I client devono tollerare questa differenza e non considerare l’assenza di un oggetto error prova di successo. Anche le risposte di validazione possono non avere un codice numerico. Considera il codice mancante sconosciuto, senza inventarlo.

API compatibili con OpenAI

Gli errori comuni della piattaforma usano code, message e type di primo livello; non sono necessariamente racchiusi in error.

{
  "code": 40000,
  "message": "Insufficient credit",
  "type": "api_error"
}

type è una categoria del protocollo; in questa struttura code è il codice numerico della piattaforma. Il solo api_error non determina se sia opportuno riprovare. Errori inoltrati dal fornitore e di streaming possono avere un error annidato: gestisci la risposta effettiva del protocollo. Consulta Chat Completions e Responses.

API compatibili con Claude

Nella struttura comune, il type di primo livello è error, la categoria specifica è error.type e la descrizione è error.message. Questa struttura non contiene un code numerico della piattaforma. Non inventarlo.

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "max_tokens must be a positive safe integer"
  }
}

La piattaforma genera localmente i seguenti tipi di errore Claude. Non è l’enumerazione completa dei tipi di errore del fornitore.

Consulta Messaggi Claude.

Errori nello stile Gemini

Quando ricevi una risposta nello stile Gemini, leggi error.code, error.message e error.status. Qui status è una categoria stringa, non uno stato HTTP o di un processo asincrono.

{
  "error": {
    "code": 10000,
    "message": "Bad request",
    "status": "INVALID_ARGUMENT"
  }
}

Gli errori della piattaforma in questa struttura usano valori numerici di piattaforma per code. La corrispondenza locale della stringa status è riportata sotto; non è un enum di tutti gli stati del fornitore.

503 ha la precedenza e usa UNAVAILABLE, non INTERNAL. Le risposte del fornitore possono attribuire significati diversi a code e status. Non applicare la tabella dei codici della piattaforma a ogni codice numerico Gemini.

Riprovare in sicurezza

Rispetta un’intestazione Retry-After valida quando presente. Non presumere che ogni errore la includa. Ripetere automaticamente una richiesta di generazione non idempotente può eseguirla di nuovo e causare altri addebiti. Questa pagina non promette supporto generale alle chiavi di idempotenza: aggiungere autonomamente Idempotency-Key non garantisce la deduplicazione.

Se hai già un jobId, consulta quel processo prima di crearne un altro. Senza jobId e con esito incerto, conserva identificatore e timestamp della richiesta per l’indagine.

Stream e processi asincroni

Richieste SSE

Dopo l’avvio di SSE, lo stato HTTP può rimanere 200 mentre un errore successivo viene segnalato tramite evento o payload nel flusso. Analizza eventi e dati del protocollo scelto e controlla il completamento normale. In caso di errore o disconnessione inattesa, non trattare testo o immagini parziali come un risultato completo riuscito. Nomi degli eventi e payload variano per endpoint. Non controllare solo un campo error fisso e non usare “ricevuto qualsiasi testo” come condizione di successo.

Processi asincroni

Una risposta di creazione contenente data.jobId indica che la richiesta è stata accettata, non che la generazione sia completa. Una risposta HTTP riuscita durante la consultazione di un processo indica solo che la query è riuscita. Devi comunque controllare data.status del processo:

• PENDING, CONNECT, PROCESSING: continua il polling come indicato nella documentazione Jobs.
• COMPLETED: leggi outputResult.
• FAILED, CANCELLED: interrompi il polling e conserva ID del processo e risposta depurata per l’indagine.

I dettagli del fallimento possono comparire in data.outputResult.error. Il campo è opzionale e non è garantito per ogni processo fallito. Usa Jobs solo quando la risposta di creazione restituisce esplicitamente un jobId. Non applicare il polling agli endpoint che restituiscono risultati direttamente via JSON o SSE.

Diagnostica per utenti e assistenti IA

Fornisci al supporto o a un assistente IA le seguenti informazioni depurate. Usa unknown per campi assenti e unknown per lo stato HTTP se non è stata ricevuta una risposta HTTP. Conserva percorsi dei campi e tipi originali, per esempio error.code: 10000 (number) o error.code: "invalid_api_key" (string). Non convertire automaticamente un code stringa in codice numerico della piattaforma e non inventare campi mancanti da message, stato HTTP o nomi dei modelli.

time_with_timezone: unknown
method: unknown
path_without_query: unknown
model: unknown
stream: unknown
http_status: unknown
error_code_path_value_and_type: unknown
error_type_path_and_value: unknown
protocol_status_path_and_value: unknown
sanitized_message: unknown
request_id_from_body_or_X-Request-ID: unknown
job_id: unknown
job_status: unknown
retry_after: unknown
retry_count_and_delays: unknown
received_partial_output: unknown

Leggi requestId dal corpo della risposta o dall’intestazione X-Request-ID, quando disponibile. Mantieni jobId come stringa per non perdere precisione con numeri lunghi. Fornisci solo parametri minimi depurati. Rimuovi chiavi API, token, cookie, intestazioni di autenticazione complete, dati personali, prompt privati e contenuti dei file di input. Rimuovi parametri di query dell’URL e URL di input/output contenenti firme o credenziali di accesso. Non incollare registri completi senza averli controllati.

Gli assistenti IA devono distinguere i campi osservati dalle possibili cause e identificare le informazioni mancanti. Prove insufficienti non devono essere considerate dimostrazione che una richiesta sia riuscita, non sia stata eseguita o non abbia generato addebiti.