Fehler behandeln
Die OpenAI-förmige Fehler-Taxonomie und was Sie wiederholen sollten.
Fehler, die Kontinent selbst erzeugt, haben die OpenAI-Form:
{ "error": { "message": "...", "type": "...", "code": "..." } }Statusreferenz
| HTTP | code | type | Bedeutung / Client-Aktion |
|---|---|---|---|
| 400 | invalid_request | invalid_request_error | Fehlerhafter Body, über 2 MiB oder fehlendes model. |
| 400 | tools_not_supported | invalid_request_error | Die Anfrage sendet tools, aber dieses Modell kann keine Tools aufrufen. Wählen Sie ein Modell, dessen supported_parameters tools enthalten. |
| 401 | invalid_api_key | invalid_request_error | Ungültiger, widerrufener, deaktivierter oder abgelaufener Schlüssel: nicht erneut versuchen. |
| 402 | insufficient_credits | insufficient_quota | Guthaben bei oder unter 0: aufladen, dann erneut versuchen. |
| 403 | model_access_blocked | invalid_request_error | Die Datenschutz-Einstellungen Ihrer Organisation oder der Guardrail des Schlüssels schließen jeden Anbieter für dieses Modell aus (Zero Retention, kein Training, nur souverän, nur § 203, Allow- oder Block-Liste). Die Meldung nennt die Regel. Nicht erneut versuchen: Einstellung in der Konsole ändern oder ein anderes Modell wählen. |
| 403 | prompt_injection_blocked | invalid_request_error | Die Anfrage passt auf eine Prompt-Injection-Regel, und der Guardrail des Schlüssels steht auf Blockieren. Die Meldung nennt die Regel. Umformulieren oder den Guardrail auf Markieren stellen. |
| 403 | segment_not_permitted | invalid_request_error | Alle infrage kommenden Anbieter schließen das registrierte Nutzungssegment Ihrer Organisation vertraglich aus oder haben (im § 203-Modus) keine Verschwiegenheitsverpflichtung unterzeichnet: nicht erneut versuchen, wählen Sie ein Modell eines anderen Anbieters. |
| 404 | model_not_found | invalid_request_error | Unbekannte oder deaktivierte Modell-ID. |
| 429 | rate_limit_exceeded | rate_limit_error | RPM pro Schlüssel erreicht (gleitendes 60-s-Fenster) oder mehr als 20 fehlgeschlagene Authentifizierungen von einer IP in der laufenden Minute. Mit Retry-After: 60: Backoff. |
| 429 | spend_limit_exceeded | insufficient_quota | Ein Ausgabelimit des Schlüssels, seines Teams oder seines Guardrails ist für den laufenden Tag, die Woche oder den Monat aufgebraucht. Ein erneuter Versuch hilft erst, wenn das Fenster neu beginnt oder das Limit erhöht wird. Siehe Budgets & Ausgabengrenzen. |
| 429 | upstream_rate_limited | rate_limit_error | Anbieter hat uns gedrosselt: mit Backoff erneut versuchen. |
| 500 | internal_error | api_error | Gateway-Bug: wiederholbar. |
| 502 | upstream_auth_error | api_error | Anbieter hat unsere Anmeldedaten abgelehnt: unser Problem. |
| 502 | upstream_error | api_error | Ein Anbieter hat geantwortet und die Antwort war unbrauchbar: ein 5xx, oder (bei einer Anfrage ohne Streaming) ein 2xx, dessen Body nicht lesbar, nicht übersetzbar oder größer als 32 MiB war. Wiederholbar, und ein anderer Anbieter lohnt sich. |
| 503 | transcriptions_busy | api_error | Auf dieser Gateway-Instanz laufen zu viele Transkriptionen gleichzeitig. Mit Retry-After: 10: nach dieser Anzahl Sekunden erneut versuchen. |
| 503 | no_provider_available | api_error | Kein Anbieter war überhaupt erreichbar. Vorübergehend und auf unserer Seite: einfach wiederholen. |
Bei einer Streaming-Anfrage gelten diese Codes nur vor dem ersten Byte. Sobald ein Stream läuft, steht der Status auf 200 und ist nicht mehr änderbar. Die Codes aus der Tabelle werden im Stream nicht wiederholt: was auch immer fehlschlägt, wird als abschließender Stream-Fehler mit error.code: "upstream_error" gemeldet. Bei /v1/chat/completions ist das ein letzter Chunk mit error auf oberster Ebene und finish_reason: "error", ohne [DONE] danach; bei /v1/responses ein response.failed-Event, dessen Response-Objekt status: "failed" und den error trägt. Der bereits erzeugte Text bleibt in beiden Fällen erhalten. Wer nur den HTTP-Status prüft, hält eine abgeschnittene Antwort für eine vollständige. Siehe Streaming.
502 und 503 sehen ähnlich aus und bedeuten Verschiedenes. 502 sagt: ein bestimmter Anbieter ist kaputt. Ein Ausweichziel oder ein anderes Modell kann jetzt schon funktionieren. 503 sagt: in der ganzen Kette hat niemand geantwortet, meist ein Netz- oder Zugangsdatenproblem auf unserer Seite, das alle Modelle dieses Anbieters gleichzeitig trifft; hier ist es richtig, dieselbe Anfrage kurz danach zu wiederholen.
Durchgereichte Fehler
Jeder Upstream-4xx außer 401, 403 und 429 (z. B. anbieterseitige Validierung Ihrer Parameter) wird unverändert mit seinem ursprünglichen Status durchgereicht. Der Body ist der des Anbieters, also meist, aber nicht immer in OpenAI-Form. Ein Upstream-401 oder -403 wird zu 502 upstream_auth_error, weil er unsere Zugangsdaten betrifft, nicht Ihre.
Hinweise zum erneuten Versuch
Wiederholbar
429 rate_limit_exceeded, 429 upstream_rate_limited, 500, 502 upstream_error, 503 no_provider_available, 503 transcriptions_busy (warten Sie Retry-After ab, wo angegeben). Nutzen Sie exponentiellen Backoff mit Jitter.
So nicht wiederholbar
400, 401, 403, 404. Beheben Sie zuerst die Anfrage, den Schlüssel oder die Einstellung. Bei 403 segment_not_permitted wählen Sie ein Modell eines anderen Anbieters, bei 403 model_access_blocked ändern Sie die in der Meldung genannte Datenschutz-Einstellung oder den Guardrail. 402 ist nur nach einer Aufladung wiederholbar, 429 spend_limit_exceeded erst, wenn das Fenster neu beginnt oder das Limit erhöht wird.
Häufige Fälle
404 model_not_found bei einem Modell, das im Dashboard sichtbar ist
Die ID muss die Form provider/model haben, und das Modell muss im Katalog aktiv sein. Prüfen Sie die exakte ID mit GET /v1/models, das alle aktiven Modelle auflistet. Gibt es die ID, schließen aber Ihre Datenschutz-Einstellungen oder Ihr Guardrail ihre Anbieter aus, erhalten Sie stattdessen 403 model_access_blocked.
400 invalid_request bei einer Anfrage, die gegen OpenAI funktioniert
Prüfen Sie die Body-Größe (das Limit sind 2 MiB) und ob model gesetzt ist. Anbieterseitige Parametervalidierung wird unverändert durchgereicht, die Meldung im Body kommt also direkt vom Anbieter.
Ein Stream endet ohne [DONE]
Failover passiert nur vor dem ersten Byte. Danach steht der Statuscode bereits auf 200, ein Anbieterfehler kommt deshalb als Chunk: ein error-Objekt auf oberster Ebene plus finish_reason: "error", und kein [DONE]. Behandeln Sie das als wiederholbaren Fehler auf Ihrer Seite, und denken Sie daran, dass die bis dahin generierten Tokens abgerechnet werden. Siehe Streaming.