Fehlercodes
Jeden OneProvider-Fehler entschlüsseln: Bedeutung der Statuscodes, genaue Meldung, Zeitlimits, Fehler mitten im Stream und wann Wiederholen sicher ist.
Was jeder Statuscode bedeutet, die genaue Meldung, die Sie sehen, und was als Nächstes zu tun ist.
Alle Modelle, Funktionen und Preise Dokumentationsindex für KI-Agenten:https://oneprovider.dev/docs/llms.txt Form des Fehlers
Jeder Fehler ist an jedem Endpoint JSON derselben Form (/v1/messages, /v1/chat/completions, /v1/responses, /v1/models). Der Guthabenfehler enthält zusätzlich code:
{
"type": "error",
"error": {
"type": "insufficient_balance",
"code": "insufficient_quota",
"message": "Insufficient balance on this API key. Top up: dashboard.oneprovider.dev"
}
}OpenAI-SDKs lesen error.message wie gewohnt aus diesem Body, sodass Sie in jedem Client denselben Text sehen.
Statuscodes
| Status | error.type | Meldung und Bedeutung | Was zu tun ist |
|---|---|---|---|
| 400 | invalid_request_error | Die Anfrage ist fehlerhaft: ungültiges JSON, ein fehlendes Feld oder ein nicht erlaubter Wert. Die Meldung nennt das Problem. | Beheben Sie, worauf die Meldung hinweist, und senden Sie die Anfrage erneut. Unverändert noch einmal gesendet, liefert sie denselben Fehler. |
| 400 | invalid_request_error | prompt is too long: N tokens > M maximum Die Eingabe ist größer als das Kontextfenster dieses Modells. N und M hängen vom Modell ab. | Kürzen Sie den Verlauf oder die Anhänge oder wählen Sie ein Modell mit größerem Kontext. Claude Code komprimiert die Unterhaltung von selbst, wenn es das sieht. |
| 400 | invalid_request_error | Model X is not available on this API key Der Tarif Ihres Schlüssels enthält dieses Modell nicht. | Wählen Sie ein Modell aus GET /v1/models oder von der Preisseite. |
| 401 | authentication_error | Invalid API key API key is required Der Schlüssel fehlt, ist falsch geschrieben oder steht im falschen Header. | Senden Sie den unveränderten sk-…-Schlüssel ohne Anführungszeichen und Leerzeichen in x-api-key oder Authorization: Bearer. |
| 401 | authentication_error | API key is disabled Der Schlüssel ist deaktiviert oder das Konto ist inaktiv. | Prüfen Sie den Schlüssel in Ihrem Konto (Seite „Schlüssel“) oder schreiben Sie an @Oneproviderhelpbot. |
| 403 | permission_error | API key expired Der Schlüssel ist abgelaufen. | Verlängern Sie den Schlüssel oder stellen Sie in Ihrem Konto (Seite „Schlüssel“) einen neuen aus. |
| 404 | not_found_error | The requested API endpoint does not exist Meist eine falsche base URL, zum Beispiel /v1/v1 im Pfad. | Claude Code und Anthropic-SDKs: https://api.oneprovider.dev. OpenAI-SDKs und OpenAI-kompatible Clients: https://api.oneprovider.dev/v1. |
| 413 | invalid_request_error | request body exceeds size limit Der Anfragekörper ist größer als 32 MB. | Senden Sie kleinere oder weniger Bilder und Dateien oder teilen Sie die Arbeit auf mehrere Anfragen auf. |
| 429 | insufficient_balance | Insufficient balance on this API key. Top up: dashboard.oneprovider.dev Das Guthaben des Kontos oder das Ausgabenlimit des Schlüssels ist aufgebraucht. Der Body enthält error.code insufficient_quota, und die Antwort hat den Header x-should-retry: false. | Nicht erneut versuchen. Laden Sie das Konto auf (Bot oder app.oneprovider.dev) oder erhöhen Sie das Limit des Schlüssels und senden Sie die Anfrage dann noch einmal. |
| 429 | rate_limit_error | Rate limit exceeded; retry later Zu viele Anfragen in kurzer Zeit. Kann einen Retry-After-Header enthalten. | Warten Sie die Sekunden aus Retry-After ab, falls vorhanden; sonst versuchen Sie es mit wachsender Pause erneut. Tritt es weiter auf, senden Sie weniger Anfragen parallel. |
| 500, 502 | server_error | Service temporarily unavailable; retry later Ein vorübergehender Fehler auf unserer Seite. | Mit wachsender Pause erneut versuchen. |
| 503 | server_error | Temporary provider issue on our side, retry in a minute Service temporarily unavailable; retry later Vorübergehend. An Ihrem Schlüssel und Ihrer Anfrage ist nichts falsch. | Mit wachsender Pause erneut versuchen; meist ist es nach einer Minute behoben. |
| 504 | server_error | Service timed out; retry later Die Anfrage hat ein Zeitlimit überschritten (siehe unten). | Erneut versuchen. Bei langen Antworten schalten Sie stream: true ein. |
Zeitlimits
- Eine Anfrage ohne Streaming muss innerhalb von 6 Minuten zu antworten beginnen.
- Jede Anfrage, auch mit Streaming, ist auf 10 Minuten begrenzt.
- Nutzen Sie für lange Generierungen
stream: true: Ein Stream beginnt sofort zu antworten. Braucht eine Antwort mehr als 10 Minuten, teilen Sie die Aufgabe auf.
Fehler innerhalb eines Streams
Sobald ein Stream läuft, ist der Status schon 200, der Fehler kommt daher als Event. Die Messages API sendet einen Frame event: error mit demselben Fehler-Body; die Responses API sendet ein Event response.failed mit dem Grund in response.error.
event: error
data: {"type":"error","error":{"type":"server_error","message":"Service temporarily unavailable; retry later"}}Behandeln Sie ihn wie den passenden Statuscode. Die Teilantwort ist unvollständig: Ist der Fehler wiederholbar, senden Sie die ganze Anfrage erneut.
Wann Sie es erneut versuchen
- Erst beheben, nicht wiederholen: 400, 401, 403, 404, 413 und 429 mit
insufficient_balance. Dieselbe Anfrage scheitert immer wieder gleich, bis Sie Anfrage, Schlüssel oder Guthaben ändern. - Mit wachsender Pause wiederholen: 429
rate_limit_error, 500, 502, 503, 504. Zum Beispiel 1 s, 2 s, 4 s und so weiter bis zu einer Minute, mit etwas zufälligem Jitter. IstRetry-Aftervorhanden, warten Sie mindestens so lange. - Beachten Sie
x-should-retry: false. Die offiziellen Anthropic- und OpenAI-SDKs tun das bereits und wiederholen den Guthabenfehler daher nicht. - Das Restguthaben prüfen Sie mit
GET /v1/dashboard/balance, siehe Verbrauch & Abrechnung .
Wie verbreitete Clients reagieren
- Claude Code. Zeigt die Meldung in der Sitzung an. Nach einem 401 entfernt Claude Code ab Version 2.1.231 den gespeicherten Schlüssel: Prüfen Sie Schlüssel und base URL (https://api.oneprovider.dev, ohne /v1) und setzen Sie den Schlüssel neu. Beim Guthabenfehler hält es sofort an: aufladen und weitermachen. Bei „prompt is too long“ komprimiert es die Unterhaltung selbst. Vorübergehende 429- und 5xx-Fehler werden automatisch wiederholt.
- Cursor. Zeigt den Fehlertext im Chat an. Prüfen Sie in den Modelleinstellungen den API-Schlüssel und die base URL https://api.oneprovider.dev/v1, laden Sie auf, wenn es um das Guthaben geht, und senden Sie erneut.
- Codex. Zeigt den Guthabenfehler als „Quota exceeded“ an und hält an: aufladen und den Befehl erneut ausführen. Vorübergehende Fehler wiederholt es zuvor von selbst.
- Cline. Zeigt den Fehler in der Aufgabe mit einer Schaltfläche „Retry“ an. Beheben Sie zuerst Schlüssel, base URL oder Guthaben und klicken Sie dann auf „Retry“.
- Continue. Zeigt den Fehlertext im Chat-Panel an. Beheben Sie die Ursache und senden Sie die Nachricht erneut.