Skip to main content

​
Error envelope

Every error response follows the OpenAI-compatible JSON shape: 
{
  "error": {
    "message": "Descriptive error message",
    "type": "invalid_request_error",
    "code": "model_not_found",
    "param": null
  }
}

​
HTTP status codes

StatusMeaningTypical cause
400Bad requestInvalid parameters, missing required fields, schema violation
401UnauthorizedMissing or invalid API key
402Payment requiredAccount quota exhausted
403ForbiddenToken has no permission for this model / group
404Not foundModel or endpoint doesn’t exist
429Too many requestsRate limit hit — see Rate Limits
500Internal errorOrcaRouter-side bug
502Upstream errorAll upstream providers failed (including fallback chain)
503Service unavailableTemporary outage

​
Streaming errors

Errors during a streamed response are emitted as SSE events, not HTTP status codes (the status was already sent when the stream opened). A streaming failure ends with: 
event: error
data: {"error":{"message":"...","type":"upstream_error"}}
followed by [DONE].

​
Fallback errors

When extra_body.models is set and all models in the chain fail, you get a 502 with details about the last upstream error. The response headers X-Orca-Fallback-Level and X-Orca-Fallback-Model indicate which fallback was being tried when the chain exhausted. See Response Headers.

​
Upstream vs OrcaRouter errors

  • Upstream errors (content policy violations, context length exceeded, provider outage) are returned with the provider’s own message and type, prefixed with a context marker so you can tell them apart.
  • OrcaRouter errors (quota exceeded, rate-limited, model not found in your group) originate from our gateway and carry OrcaRouter-specific codes like model_price_error, quota_insufficient, fallback_exhausted.
If you need to programmatically distinguish, check the error.type field against the list documented per endpoint.