Error responses
Parse the common Router error envelope and recover according to status and code.
Router returns errors as JSON before a stream starts.
{ "error": { "message": "No provider is available for this model", "type": "server_error", "code": "no_provider_available" }}Use the HTTP status for broad control flow, the stable code for a specific product message, and message for a human-readable explanation.
Common API errors
| Status | Code or category | Recovery |
|---|---|---|
| 400 | Invalid body, unknown model, output_limit, or unsupported input | Correct the request before trying again. |
| 401 | auth_no_token or invalid_api_key | Supply a valid bearer key or rotate an expired or revoked key. |
| 403 | account_disabled | Resolve account access; repeated requests will not help. |
| 429 | Request-rate or concurrency limit | Respect Retry-After and reduce parallel work. |
| 503 | no_provider_available | No free matching provider exists now; retry later with backoff. |
| 503 | request_capacity | Router’s bounded active-request capacity is full; retry later. |
| 503 | Generation or dependency failure | Show a temporary failure and retry only when safe. |
Error messages can evolve. Branch application behavior on status and code rather than matching the English message.
Streaming errors
After streaming headers are sent, a generation failure arrives as an SSE data event with an error object. The HTTP status may already be 200.
data: {"error":{"message":"Generation interrupted","type":"server_error","code":"inference_failed"}}An error event is terminal for that generation. Do not wait for [DONE], and do not treat already-received content as a complete answer.
Retry headers
429 and temporary capacity responses can include Retry-After. Interpret an integer value as seconds, add jitter before retrying, and keep the total number of attempts bounded.
See retries, timeouts, and cancellation for an application strategy.