> For the complete documentation index, see [llms.txt](https://docs.kontinent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kontinent.ai/documentation/dokumentation/features/errors.md). # Fehler behandeln Fehler haben immer die OpenAI-Form: ```json { "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`. | | 401 | `invalid_api_key` | `invalid_request_error` | Ungültiger oder widerrufener Schlüssel: **nicht erneut versuchen**. | | 402 | `insufficient_credits` | `insufficient_quota` | Guthaben bei oder unter 0: aufladen, dann erneut versuchen. | | 403 | `segment_not_permitted` | `invalid_request_error` | Alle infrage kommenden Anbieter schließen das registrierte Nutzungssegment Ihrer Organisation vertraglich aus: **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: Backoff (gleitendes 60-s-Fenster). | | 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 | `no_provider_available` | `api_error` | Kein Anbieter war überhaupt **erreichbar**. Vorübergehend und auf unserer Seite: einfach wiederholen. | {% hint style="warning" %} **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](/documentation/dokumentation/features/streaming.md). {% endhint %} {% hint style="info" %} `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. {% endhint %} ## Durchgereichte Fehler Upstream-4xx-Bodies, die bereits die OpenAI-Form haben (z. B. anbieterseitige Validierung Ihrer Parameter), werden **mit ihrem ursprünglichen Status durchgereicht** statt neu verpackt. ## Hinweise zum erneuten Versuch

:rotate:

Wiederholbar429, 500, 502 upstream_error, 503 no_provider_available. Nutzen Sie exponentiellen Backoff mit Jitter.

:ban:

So nicht wiederholbar400, 401, 403, 404. Beheben Sie zuerst die Anfrage oder den Schlüssel. Bei 403 wählen Sie ein Modell eines anderen Anbieters. 402 ist nur nach einer Aufladung wiederholbar.
## 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 für Ihre Organisation aktiviert sein. Prüfen Sie die exakte ID mit `GET /v1/models`: dieser Endpunkt liefert nur, was Ihre Organisation tatsächlich aufrufen kann.
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](/documentation/dokumentation/features/streaming.md).
## Verwandte Seiten {% content-ref url="/pages/C60Fkrhcy4lYisPZjqIi" %} [Rate-Limits & Guthaben](/documentation/dokumentation/features/rate-limits.md) {% endcontent-ref %} {% content-ref url="/pages/Pc1PnBhujjeKjhpJsNqT" %} [Authentifizierung](/documentation/dokumentation/overview/authentication.md) {% endcontent-ref %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.kontinent.ai/documentation/dokumentation/features/errors.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.