Zum Hauptinhalt springen

​
Fehlerhülle

Die meisten Fehlerantworten verwenden diese OpenAI-kompatible JSON-Form: 
{
  "error": {
    "message": "Descriptive error message",
    "type": "orcarouter_api_error",
    "code": "model_not_found"
  }
}
type ist eine breite Kategorie, code ist ein spezifischer Identifier. Einige Schnellpfad-Fehler (insbesondere 429er auf Workspace-Ebene) geben nur einen HTTP-Statuscode mit den relevanten Headern und keinen JSON-Body zurück.

​
HTTP-Statuscodes

StatusBedeutungTypische Ursache
400Ungültige AnfrageUngültige Parameter, fehlende Pflichtfelder, Schema-Verletzung
401Nicht autorisiertFehlender oder ungültiger API-Schlüssel
403VerbotenUnzureichendes Kontingent oder der Schlüssel kann dieses Modell nicht aufrufen
404Nicht gefundenModell oder Endpunkt existiert nicht
429Zu viele AnfragenRatenlimit erreicht — siehe Ratenlimits. Die Antwort enthält immer einen Retry-After-Header.
500Interner FehlerOrcaRouter-seitiger Bug
502Upstream-FehlerAlle Upstream-Anbieter sind fehlgeschlagen (einschließlich jeder Fallback-Kette)
503Dienst nicht verfügbarDas angeforderte Modell ist im Upstream vorübergehend nicht verfügbar

​
Fehlertypen, die du in error.type sehen kannst

error.typeWoher es kommt
orcarouter_api_errorGateway-seitige Fehler (Auth, Kontingent, Rate, intern)
upstream_errorDer Upstream-Anbieter hat einen Fehler zurückgegeben oder ist ausgelaufen
openai_errorOpenAI-kompatibler Upstream-Fehler wörtlich erhalten
claude_errorAnthropic-Upstream-Fehler wörtlich erhalten
gemini_errorGemini-Upstream-Fehler wörtlich erhalten

​
Fehlercodes, die du in error.code sehen kannst

Dies sind vom Gateway ausgegebene Codes für Fehler, die in OrcaRouter (nicht im Upstream) entstehen:
error.codeHTTPBedeutung
insufficient_user_quota403Kontokredit erschöpft. Aufladen.
model_not_found503Dieses Modell ist für dein Konto nicht verfügbar.
model_price_error400Die Preisgestaltung für dieses Modell ist nicht eingerichtet. Support kontaktieren.
api_not_implemented400Endpunkt oder Operation nicht unterstützt für das gewählte Modell.
bad_request_body400Anfragekörper konnte nicht geparst werden.
prompt_blocked400Sicherheitsrichtlinie des Anbieters hat den Prompt vor der Generierung blockiert.
sensitive_words_detected400Filter für sensible Inhalte hat den Prompt abgelehnt.
Wenn du programmatisch unterscheiden musst, matche zuerst auf error.code (spezifisch) und falle zurück auf error.type (breite Kategorie).

​
Streaming-Fehler

Fehler während einer gestreamten Antwort können keine HTTP-Statuscodes verwenden (der Status wurde beim Öffnen des Streams gesendet). Das Format hängt vom Endpunkt ab:

​
/v1/chat/completions und /v1/responses (OpenAI-kompatibel)

Der Fehler kommt als In-Band-data: {...}-Chunk an: 
data: {"error":{"message":"...","type":"upstream_error","code":""}}

data: [DONE]
Parse jeden data:-Chunk als JSON; wenn er ein error-Feld hat, behandle den Stream als fehlgeschlagen.

​
/v1/messages (Anthropic-kompatibel)

Anthropic verwendet benannte SSE-Ereignisse. Ein Stream-Fehler kommt an als: 
event: error
data: {"type":"error","error":{"type":"overloaded_error","message":"..."}}
Der Stream endet mit event: message_stop (oder wird abgeschnitten) nach dem Fehlerereignis.

​
Fallback-Fehler

Wenn extra_body.models gesetzt ist und alle Modelle in der Kette fehlschlagen, erhältst du ein 502 mit Details zum letzten Upstream-Fehler. Die Antwort-Header X-Orca-Fallback-Level und X-Orca-Fallback-Model zeigen an, welches Fallback versucht wurde, als die Kette erschöpft war. Siehe Antwort-Header.