Errors and retries

Before an OpenAI-compatible stream begins, API errors use this structure:

{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key is invalid or expired.",
    "type": "invalid_request_error",
    "param": null
  }
}

This is an illustrative authentication error. Match the HTTP status and machine-readable code; do not parse human-readable error messages.

Status guide

Status	Typical cause	Action
`400`	Invalid JSON, missing model/input, unsupported feature, or provider rejection.	Correct the request before retrying.
`401`	Missing, invalid, expired, or revoked customer key.	Check or replace the key.
`402`	Available credits or spending allowance cannot cover admission.	Review Billing and Limits.
`403`	Missing key scope, insufficient console role, or an enforcing policy match.	Check permissions or the policy error code.
`404`	Missing route or unavailable model.	Check the path and model catalog.
`409`	Stale policy revision, conflicting idempotency key, or invalid resource state.	Retrieve the current resource before another mutation.
`405`	Unsupported HTTP method.	Use the method listed in the `Allow` header.
`408`	Request-body upload did not finish in time.	Check the client connection.
`413`	Request body exceeds 8 MiB.	Reduce the payload.
`415`	Content type is not JSON.	Send `Content-Type: application/json`.
`429`	Workspace limit or upstream capacity exceeded.	Respect `Retry-After` when present and back off.
`500`	Unexpected server failure.	Keep the request ID and inspect Activity before replaying.
`502`	Inference backend failed.	Retry only when appropriate for your workflow.
`503`	Required service/configuration or usage persistence is unavailable.	Wait or contact the beta operator.
`504`	Inference exceeded the gateway deadline.	Review Activity and reduce the workload if needed.

Common stable codes include invalid_request, invalid_model, unsupported_feature, provider_rejected_request, rate_limited, provider_unavailable, usage_unavailable, and inference_timeout. Backend details and credentials are not included in error messages. Prepaid admission uses these more specific codes:

Code	Status	Meaning
`insufficient_credit`	`402`	Available wallet funds cannot cover the reservation.
`monthly_budget_exceeded`	`402`	The monthly cap cannot cover another reservation.
`rate_limit_exceeded`	`429`	The workspace has exhausted its rolling request allowance.
`concurrency_limit_exceeded`	`429`	The workspace’s concurrent request slots are occupied.
`model_unavailable`	`400`	The requested model is absent from the enabled price catalog.
`model_not_priced`	`503`	Model pricing became unavailable during database admission.

Streaming errors

After HTTP headers have been sent, the server cannot replace the response with a different status. A stream may end early or carry a provider failure event. Catch SDK iteration errors, inspect terminal events, and check Activity; a 200 alone does not prove completion.

Retry deliberately

The gateway performs no automatic upstream inference retries. The official SDKs may retry some failures unless you set JavaScript maxRetries: 0 or Python max_retries=0, as in the quickstart. Inference POST requests are not deduplicated by an idempotency key. Replaying a request can generate another response and incur another charge, even if the first response was lost in transit. For interactive applications, show an explicit retry action after partial output. For jobs, store your own job state and use bounded exponential backoff with jitter. Capture X-Request-ID for diagnosis. Never include your API key in logs or support messages.

Messages, administration, and policies

Messages errors add a top-level type: "error" and use Anthropic-style categories such as authentication_error and rate_limit_error. Continue matching the HTTP status and error.code. Administrative errors and policy errors include error.request_id. A stale policy revision returns 409 with policy_revision_conflict; read the latest revision before editing. Creation retries must keep the same idempotency key and payload. An expired key-secret replay window returns idempotency_reconciliation_required; inspect existing keys before issuing another. A blocking policy can return policy_violation; an unavailable evaluator can return policy_evaluation_unavailable. These use policy_error. Do not silently disable a policy to retry an otherwise rejected request.

Start here

Build

Administer

Operate

Errors and retries

Status guide

Streaming errors

Retry deliberately

Messages, administration, and policies

​Status guide

​Streaming errors

​Retry deliberately

​Messages, administration, and policies

Status guide

Streaming errors

Retry deliberately

Messages, administration, and policies