Developer guide
Codici di errore
Gestione e regole di nuovo tentativo per codice di stato
Questa pagina riepiloga i codici di stato restituiti dal gateway, il loro significato e le azioni da intraprendere per ciascun codice.
Se l'upstream restituisce un codice 4xx o 5xx, il codice viene inoltrato così com'è; negli altri casi si applica la tabella seguente.
Sono inoltre descritti il formato dei corpi degli errori per i due standard compatibili, le regole di error.type compatibili con Anthropic e la schermata della console per verificare limiti e utilizzo.
Codice di stato
| Codice | Significato | Azione |
|---|---|---|
| 400 | Errore nei valori della richiesta. Il valore di limit dell'elenco dei modelli compatibili con Anthropic è fuori dall'intervallo 1~1000, oppure si è tentato di riprendere una risposta salvata con GET /responses/{responseId}?stream=true | Correggere il valore in modo che rientri nell'intervallo. Consultare le risposte salvate senza stream. |
| 401 | Chiave assente, scaduta o revocata | Verificare lo stato della chiave nella schermata delle chiavi API e controllare il nome dell'intestazione e il prefisso Bearer. |
| 403 | Nessuna autorizzazione per accedere al modello, superamento del limite di utilizzo, crediti insufficienti o mancata corrispondenza con il proprietario della voce | error.message indica il motivo specifico. I valori numerici sono disponibili nella schermata della sezione seguente, Verifica dei limiti e dell'utilizzo. |
| 404 | Modello inesistente o non accessibile con questa chiave (inclusi i modelli non più supportati), percorso inesistente oppure output di CleviDrive per cui sono trascorsi 3 giorni dal periodo di conservazione | Prima verificare l'elenco dei modelli richiamabili con GET /models. Confrontare il percorso con la tabella nella pagina Effettuare chiamate API. |
| 408 · 409 · 413 | Timeout dell'upstream, congestione o dimensione della richiesta eccessiva. Per i percorsi vocali e voice, il limite di tempo è 5 minuti e il limite della richiesta è 28 MiB | Se 409 include Retry-After, attendere per il tempo indicato. Per 413, suddividere la richiesta prima dell'invio. |
| 429 | Il provider upstream ha applicato un limite di velocità | Se è presente Retry-After, seguirlo così com'è; in caso contrario, riprovare con un backoff esponenziale. |
| 5xx | Errore temporaneo del gateway o dell'upstream (incluso 503) | Riprovare con un backoff esponenziale. Se il problema persiste, segnalarlo tramite la guida e il modulo di contatto, includendo X-Request-Id. |
Nuovo tentativo
Il gateway non genera autonomamente 429 e non riprova né accoda le risposte dell'upstream senza comunicarlo.
L'attesa e i nuovi tentativi sono gestiti dal client.
| Codice | Tempo di attesa | Quindi |
|---|---|---|
| 409 | Se è presente Retry-After, attendere per quel periodo | Inviare nuovamente la stessa richiesta. |
| 429 | Se è presente Retry-After, attendere per quel periodo; in caso contrario, utilizzare il backoff esponenziale | Inviare nuovamente la stessa richiesta. |
| 5xx | Backoff esponenziale | Se si ripete, contattare l'assistenza. |
| 413 | Nessuna attesa | Suddividere la richiesta. |
Corpo dell'errore
Il corpo dell'errore ha una struttura diversa a seconda della specifica. Per gli errori upstream, trasmettiamo solo il messaggio dopo averlo ripulito; stack e campi interni non vengono inoltrati.
Corpo della richiesta per il percorso compatibile con OpenAI.
{
"error": {
"message": "API key is required.",
"type": "invalid_request_error"
}
}Corpo della richiesta per il percorso compatibile con Anthropic. error.type è determinato dal codice di stato.
{
"type": "error",
"error": {
"type": "authentication_error",
"message": "..."
},
"request_id": "rqid..."
}| Codice di stato | error.type |
|---|---|
| 400 | invalid_request_error |
| 401 | authentication_error |
| 403 | permission_error |
| 404 | not_found_error |
| 413 | request_too_large |
| 429 | rate_limit_error |
| 529 | overloaded_error |
| Altri codici | api_error |
Verifica dei limiti e dell'utilizzo
I valori dei limiti variano a seconda dell'area di lavoro. Dopo aver verificato il motivo del 403 in error.message, controllate i valori nelle schermate seguenti.
| Elemento da verificare | Schermata della console |
|---|---|
| Limite applicato alla mia area di lavoro | Limite di utilizzo assegnato nella panoramica |
| Intervallo consentito dal piano e saldo | Piano e crediti |
| Utilizzo effettivo (numero di chiamate per modello e chiave, crediti stimati da detrarre) | Utilizzo |
| Stato della chiave (scadenza o revoca) | Chiavi API |