Errori
Gli errori seguono il formato OpenAI, così gli SDK li trasformano nelle loro eccezioni (AuthenticationError, RateLimitError e così via):
{
"error": {
"message": "…",
"type": "rate_limit_error",
"param": null,
"code": "rate_limit_exceeded"
}
} | HTTP | code | Quando | Cosa fare |
|---|---|---|---|
| 400 | invalid_request | Parametri non validi, n diverso da 1, max_tokens oltre il massimo, contesto troppo lungo | Correggi la richiesta (vedi param e message) |
| 400 | request_too_large | Richiesta più grande di quanto il piano legga in una volta (Free: circa 30.000 token) | Accorcia i messaggi o passa a un piano a pagamento |
| 401 | missing_api_key | Manca la chiave | Aggiungi Authorization: Bearer … |
| 401 | invalid_api_key | Chiave sbagliata o revocata | Crea una nuova chiave nella console |
| 401 | api_key_expired | La chiave è scaduta: il messaggio dice quando | Crea una nuova chiave nella console |
| 403 | organization_inactive | Organizzazione in lista d’attesa o sospesa | Attendi l’attivazione o scrivici |
| 403 | terms_not_accepted | Accesso con un account (non con una chiave API) che non ha ancora accettato termini e regole d’uso | Accettali nella chat o nella console |
| 403 | api_not_in_plan | Chiave API di un’organizzazione sul piano Free, che comprende solo la Chat | Passa al piano Plus o superiore |
| 403 | model_not_allowed | Modello riservato alle organizzazioni verificate, o al supplemento Extreme sui piani a pagamento | Chiedi la verifica nella console, pagina Piano |
| 404 | model_not_found | Modello inesistente o non incluso nel tuo piano | Controlla GET /v1/models |
| 429 | rate_limit_exceeded | Quota delle ultime 5 ore o degli ultimi 7 giorni esaurita, oppure troppe richieste contemporanee | Riprova dopo Retry-After secondi |
| 429 | insufficient_quota | Quota del mese o del periodo di 30 giorni esaurita | Si azzera il primo del mese o al rinnovo; vedi la console |
| 429 | too_many_failed_requests | Troppe richieste fallite dallo stesso indirizzo (chiave sbagliata, percorsi inesistenti): 30 in 10 minuti | Correggi la chiave e riprova dopo Retry-After secondi |
| 502 | upstream_error | Errore del modello | Riprova; se si ripete, scrivici con x-request-id |
| 500 | internal_error | Errore nostro, non previsto | Riprova; se si ripete, scrivici con x-request-id |
| 503 | server_overloaded | Coda piena o attesa troppo lunga | Riprova dopo Retry-After (gli SDK lo fanno da soli) |
| 503 | model_unavailable | Modello momentaneamente non disponibile | Riprova dopo Retry-After |
| 503 | safety_unavailable | Il controllo delle linee rosse non risponde: per sicurezza non procediamo | Riprova tra poco |
| 503 | upstream_unavailable | Il modello non è raggiungibile | Riprova dopo Retry-After |
| 503 | auth_unavailable | Accesso con un account (non con una chiave API): il sistema di accesso non risponde | Riprova dopo Retry-After |
| 504 | upstream_timeout | Il modello non ha cominciato a rispondere in tempo | Riprova |
Riprovare
- Ogni 429 e 503 porta
Retry-After(secondi). - Quando una quota è esaurita aggiungiamo
x-should-retry: false: gli SDK di OpenAI non riprovano da soli, perché l’attesa può essere di ore. - Per i 503 gli SDK riprovano con un’attesa crescente: va bene così.
- Se gli errori 5xx durano, controlla status.beatriceai.it: lì trovi lo stato di API, modello e accesso, e gli incidenti in corso.
Rifiuti sulle linee rosse
Non sono errori: la risposta è normale (HTTP 200) con finish_reason: "content_filter" e un testo che spiega quale regola si applica. Vedi Linee rosse.