Codici di errore
Decifra gli errori di OneProvider: significato di ogni codice di stato, messaggio esatto, limiti di tempo, errori a metà stream e quando riprovare.
Cosa significa ogni codice di stato, il messaggio esatto che vedrai e cosa fare dopo.
Tutti i modelli, le funzionalità e i prezzi Indice della documentazione per agenti AI:https://oneprovider.dev/docs/llms.txt Forma dell'errore
Ogni errore è un JSON della stessa forma su ogni endpoint (/v1/messages, /v1/chat/completions, /v1/responses, /v1/models). L'errore di saldo contiene anche code:
{
"type": "error",
"error": {
"type": "insufficient_balance",
"code": "insufficient_quota",
"message": "Insufficient balance on this API key. Top up: dashboard.oneprovider.dev"
}
}Gli SDK OpenAI leggono error.message da questo corpo come al solito, quindi vedi lo stesso testo in qualsiasi client.
Codici di stato
| Stato | error.type | Messaggio e significato | Cosa fare |
|---|---|---|---|
| 400 | invalid_request_error | La richiesta è malformata: JSON non valido, un campo mancante o un valore non consentito. Il messaggio indica il problema. | Correggi ciò che indica il messaggio e invia di nuovo. Se la reinvii invariata, ottieni lo stesso errore. |
| 400 | invalid_request_error | prompt is too long: N tokens > M maximum L'input è più grande della finestra di contesto di questo modello. N e M dipendono dal modello. | Accorcia la cronologia o gli allegati, oppure scegli un modello con un contesto più ampio. Claude Code compatta la conversazione da solo quando vede questo errore. |
| 400 | invalid_request_error | Model X is not available on this API key Il piano della tua chiave non include questo modello. | Scegli un modello presente in GET /v1/models o nella pagina dei prezzi. |
| 401 | authentication_error | Invalid API key API key is required La chiave manca, è scritta male o è inviata nell'header sbagliato. | Invia la chiave sk-… così com'è, senza virgolette né spazi, in x-api-key o Authorization: Bearer. |
| 401 | authentication_error | API key is disabled La chiave è disattivata o l'account è inattivo. | Controlla la chiave nella tua area personale (pagina «Chiavi») oppure scrivi a @Oneproviderhelpbot. |
| 403 | permission_error | API key expired La chiave ha superato la data di scadenza. | Rinnova la chiave oppure emettine una nuova nella tua area personale (pagina «Chiavi»). |
| 404 | not_found_error | The requested API endpoint does not exist Di solito una base URL sbagliata, per esempio /v1/v1 nel percorso. | Claude Code e gli SDK Anthropic: https://api.oneprovider.dev. Gli SDK OpenAI e i client compatibili con OpenAI: https://api.oneprovider.dev/v1. |
| 413 | invalid_request_error | request body exceeds size limit Il corpo della richiesta supera i 32 MB. | Invia immagini e file più piccoli o in numero minore, oppure dividi il lavoro in più richieste. |
| 429 | insufficient_balance | Insufficient balance on this API key. Top up: dashboard.oneprovider.dev Il saldo dell'area personale o il limite di spesa della chiave è esaurito. Il corpo contiene error.code insufficient_quota e la risposta ha l'header x-should-retry: false. | Non riprovare. Ricarica l'area personale (bot o app.oneprovider.dev) oppure alza il limite della chiave, poi invia di nuovo la richiesta. |
| 429 | rate_limit_error | Rate limit exceeded; retry later Troppe richieste in poco tempo. Può includere un header Retry-After. | Se presente, attendi i secondi indicati da Retry-After, altrimenti riprova con una pausa crescente. Se continua, invia meno richieste in parallelo. |
| 500, 502 | server_error | Service temporarily unavailable; retry later Un errore temporaneo da parte nostra. | Riprova con una pausa crescente. |
| 503 | server_error | Temporary provider issue on our side, retry in a minute Service temporarily unavailable; retry later Temporaneo. Non c'è nulla che non vada nella tua chiave o nella tua richiesta. | Riprova con una pausa crescente; di solito si risolve in non più di un minuto. |
| 504 | server_error | Service timed out; retry later La richiesta ha superato un limite di tempo (vedi sotto). | Riprova. Per le risposte lunghe attiva stream: true. |
Limiti di tempo
- Una richiesta senza streaming deve iniziare a rispondere entro 6 minuti.
- Qualsiasi richiesta, streaming incluso, è limitata a 10 minuti.
- Per le generazioni lunghe usa
stream: true: uno stream inizia a rispondere subito. Se una risposta richiede più di 10 minuti, dividi il compito.
Errori dentro uno stream
Quando uno stream è iniziato, lo stato è già 200, quindi l'errore arriva come evento. La Messages API invia un frame event: error con lo stesso corpo di errore; la Responses API invia un evento response.failed con il motivo in response.error.
event: error
data: {"type":"error","error":{"type":"server_error","message":"Service temporarily unavailable; retry later"}}Gestiscilo come il codice di stato corrispondente. La risposta parziale è incompleta: se l'errore è ritentabile, invia di nuovo l'intera richiesta.
Quando riprovare
- Prima correggi, non riprovare: 400, 401, 403, 404, 413 e 429 con
insufficient_balance. La stessa richiesta fallisce nello stesso modo finché non cambi la richiesta, la chiave o il saldo. - Riprova con una pausa crescente: 429
rate_limit_error, 500, 502, 503, 504. Per esempio 1 s, 2 s, 4 s e così via fino a un minuto, con un po' di jitter casuale. SeRetry-Afterè presente, attendi almeno quel tempo. - Rispetta
x-should-retry: false. Gli SDK ufficiali di Anthropic e OpenAI già lo fanno, quindi non ritentano l'errore di saldo. - Controlla cosa resta con
GET /v1/dashboard/balance, vedi Consumo e fatturazione .
Come reagiscono i client più diffusi
- Claude Code. Mostra il messaggio nella sessione. Dopo un 401, Claude Code 2.1.231 e successivi rimuove la chiave salvata: controlla la chiave e la base URL (https://api.oneprovider.dev, senza /v1), poi imposta di nuovo la chiave. Con l'errore di saldo si ferma subito: ricarica e prosegui. Con "prompt is too long" compatta da solo la conversazione. Gli errori temporanei 429 e 5xx vengono ritentati in automatico.
- Cursor. Mostra il testo dell'errore nella chat. Controlla la chiave API e la base URL https://api.oneprovider.dev/v1 nelle impostazioni del modello, ricarica se il messaggio riguarda il saldo, poi invia di nuovo.
- Codex. Mostra l'errore di saldo come "Quota exceeded" e si ferma: ricarica ed esegui di nuovo il comando. Gli errori temporanei vengono prima ritentati in autonomia.
- Cline. Mostra l'errore nell'attività con un pulsante Retry (Riprova). Correggi prima la chiave, la base URL o il saldo, poi premi Retry.
- Continue. Mostra il testo dell'errore nel pannello della chat. Rimuovi la causa e invia di nuovo il messaggio.