Errors and retries
Interpret HTTP statuses and stream errors, then choose a safe next action.
Save x-request-id before reading the body. For an interrupted stream, keep the HTTP headers and any final error event. Open Analytics → Requests to inspect the recorded result and failure reason; early unauthenticated failures may have no account history row.
Error envelopes
Chat Completions uses an OpenAI-shaped envelope. This example represents a missing or invalid gateway key:
{
"error": {
"message": "A valid API key is required",
"type": "invalid_api_key",
"param": null,
"code": "invalid_api_key"
}
}Messages uses an Anthropic-shaped envelope for the same failure:
{
"type": "error",
"error": {
"type": "authentication_error",
"message": "A valid API key is required"
}
}For HTTP 402, OpenAI-format responses use insufficient_credits; Anthropic-format responses use billing_error. Both a low credit balance and a monthly key limit can produce this status. Read the locally generated message to distinguish them. Provider error text is replaced with a safe message; it is not a copy of the provider's response.
Status, cause, next action
| Status | Typical cause | What you do |
|---|---|---|
400 | Invalid field, unsupported option, too much input, or output budget above the model limit | Check param when available, remove the rejected feature, or reduce input/output budget. |
401 | Missing, invalid or revoked gateway key; exhausted fallback after a provider authentication failure can also surface this status | Use your saved active key, or create a new one in API Keys. If other calls with the same key work, retain the request ID and inspect the failed request. |
402 | Insufficient available credits, or the key's monthly limit would be exceeded | Check Credits, active holds and API Keys settings. Lower the requested output budget when appropriate. |
403 | Model excluded by the key's allowed list or account routing filters | Allow the model in both places. Neither setting overrides the other. |
404 | Unknown model or unsupported route | Copy the model ID from Marketplace. Use one of the four public endpoints. |
408 | A streaming client stops reading long enough to be disconnected | Consume the stream continuously; check your client or proxy buffering. This may appear in request history after the connection ends. |
409 | A request's usage/reservation cannot be reconciled with its current capacity | Inspect Requests and credits before resubmitting; quote the request ID if the outcome is unclear. |
413 | Request body exceeds the accepted payload size | Reduce the body, image payloads or conversation history. |
429 | Key rate limit or provider rate limit | Respect Retry-After when present and reduce parallel calls. |
499 | Client disconnects before completion | Check client cancellation and timeout settings. This is a recorded outcome; the disconnected client cannot receive it as a new HTTP response. |
500 | Provider or gateway cannot complete the request | Inspect history before a bounded retry; keep the request ID. |
502 | Invalid provider response or unexpectedly ended upstream stream | Inspect for a partial response, then retry with backoff if appropriate. |
503 | No suitable offer, exhausted capacity, temporary overload or no remaining healthy candidate | Check Marketplace, model filters and your price cap. Respect Retry-After when present. Handled inference 503 responses include Retry-After: 1 before a stream starts; do not assume every endpoint returns it. |
504 | Provider/request timeout | Check whether streaming was enabled and whether the client saw partial output. Retry with a bounded budget if appropriate. |
529 | Provider overload | Back off and try later; availability is not guaranteed. |
The exact error type is format-dependent. A generic api_error does not identify a provider-specific error code.
Retrying streams
The gateway can fall back before sending response bytes, trying at most three offers. After output begins, an error is an event within the existing stream, not a new HTTP status and not a switch to another seller. OpenAI streams carry an error object in a data: event; Anthropic streams use event: error.
Treat partial output as incomplete. Retrying creates a new request and can incur another charge. SDKs may also retry automatically; choose a bounded retry policy and log each request ID. If your agent has already run a tool with a side effect, inspect that result before allowing it to repeat the action.
Report a problem
Include the x-request-id, approximate UTC time, model ID, client name/version, endpoint and whether you used streaming. Include the safe error message or failure reason and explain whether any output arrived. Do not send the API key, provider credentials or private prompt content.