Errori

La struttura dell'errore

{
  "error": {
    "message": "Human-readable description of what went wrong",
    "type": "invalid_request_error"
  }
}

Questa è la stessa struttura usata dall'API di OpenAI, quindi la gestione degli errori scritta per un client esistente compatibile con OpenAI dovrebbe continuare a funzionare senza modifiche: controlli prima il codice di stato HTTP, poi legga error.message per un messaggio utile da mostrare a uno sviluppatore o da registrare nei log. error.type è una categoria stabile, verificabile a livello di codice, utile per la logica di diramazione (ritentare o no, chiedere una nuova chiave API oppure attendere e riprovare) senza dover analizzare il messaggio in testo libero.

Codici di stato e tipi

Stato	Tipo	Significato
400	invalid_request_error	La richiesta stessa è malformata: un model non riconosciuto, un array messages mancante o vuoto, un messaggio con un ruolo non supportato, o una definizione tools malformata. Corregga la richiesta; ritentare senza cambiare nulla fallirà allo stesso modo ogni volta.
401	authentication_error	L'header Authorization è mancante, malformato, oppure la chiave non è valida, è scaduta o è stata revocata. Vedere Autenticazione.
429	rate_limit_error	Troppe richieste in una finestra di tempo breve su questa chiave. Vedere Limiti di frequenza per il limite e come attendere correttamente prima di riprovare.
500	api_error	Un errore lato server inatteso non correlato alla sua richiesta. Raro; sicuro da ritentare, idealmente con una breve attesa.
503	api_error	Il servizio non è temporaneamente in grado di completare la richiesta, tipicamente un problema transitorio sull'infrastruttura di generazione di tAI stessa piuttosto che qualcosa di sbagliato nella sua richiesta. Sicuro da ritentare.

Alcuni esempi

Un modello sconosciuto:

HTTP/1.1 400 Bad Request

{"error": {"message": "Unknown model: 'tai-4.9'. See https://docs.artfical.com/tai/en for the current list.", "type": "invalid_request_error"}}

Una chiave non valida o scaduta:

HTTP/1.1 401 Unauthorized

{"error": {"message": "Invalid API key.", "type": "authentication_error"}}

Un problema transitorio del servizio:

HTTP/1.1 503 Service Unavailable

{"error": {"message": "The AI service is temporarily unavailable. Please retry.", "type": "api_error"}}

Errori a metà dello stream

Una volta che una risposta in streaming è iniziata (la connessione è aperta e i chunk hanno iniziato ad arrivare), un errore non può più essere segnalato come un normale corpo di errore JSON con uno stato non-2xx, poiché lo stato HTTP e gli header sono già stati inviati come 200 all'inizio dello stream. Invece, un fallimento che avviene a metà dello stream viene mostrato come un chunk di contenuto visibile (tipicamente un breve avviso tra parentesi quadre) seguito da un normale chunk finale e da [DONE], invece che dalla semplice caduta della connessione. Vedere Streaming per la forma esatta e perché lo stream è comunque garantito terminare in modo pulito.

Cosa vale la pena ritentare

Come regola generale: gli errori 400 e 401 descrivono qualcosa di sbagliato nella richiesta o nella chiave stessa, e ritentare in modo identico fallirà in modo identico ogni volta, quindi risolva prima il problema di fondo. 429, 500 e 503 sono tutti sicuri da ritentare, idealmente con un breve ritardo e un limite al numero totale di tentativi, invece di ritentare in un ciclo stretto; vedere Limiti di frequenza nello specifico per come attendere correttamente dopo un 429.