Errors

Every error the gateway returns is an OpenAI-compatible envelope with a stable code. The messages are written so an agent can self-correct from the code and message alone.

The error envelope

Every failure on /v1/chat/completions, /v1/responses, and /v1/models returns the same shape, so existing OpenAI error handling keeps working:

{
  "error": {
    "message": "The requested model alias is not granted to this identity.",
    "type": "permission_error",
    "code": "model_not_granted",
    "param": null
  }
}

Branch on code, not the message text; the message is human-readable and may change, the code is stable.

Stable codes

code	HTTP	Meaning	How to recover
model_location_not_supported	403	The request location is outside this model maker's supported regions, or could not be verified.	Choose another model or contact support if the location is incorrect. Retrying, changing keys, or adding credits will not resolve this policy refusal.
invalid_json	400	The request body is not valid JSON.	Fix the request body.
invalid_request	400	The request is malformed.	Read the message, fix the request, and resend.
invalid_parameter	400	A field is invalid; param names it.	Correct that field and resend.
unsupported_capability	400	A whole capability the model route does not expose (a tool, a modality, reasoning) was requested.	Pick a capable model; check supported_params and modalities in /api/models.
unsupported_parameter	400	A specific request parameter the model route rejects (e.g. temperature on a reasoning-only route, or top_k / frequency_penalty / presence_penalty / top_logprobs where the route does not accept them); param names it.	Remove the field, or choose a model whose Supported parameters include it (shown on the model page).
previous_response_not_found	400	previous_response_id is unknown or expired on this worker.	Resend the full conversation instead of continuing.
invalid_key	401	The key is missing, malformed, expired, or revoked.	Fix the Authorization header.
model_not_granted	403	Your organization cannot call this slug.	Use a slug returned by GET /v1/models.
idempotency_conflict	409	The same Idempotency-Key was reused with a different body.	Use a fresh Idempotency-Key.
idempotency_replay_unavailable	409 / 500	The original keyed result is gone after a restart.	Resend with a new Idempotency-Key.
insufficient_quota	429	A spend limit or your credit balance is exhausted; the message says which (a daily org cap, a per-model cap, or credits).	Add credits or raise limits at /credits (platform-funded lane only).
unavailable_route	429 / 503	Throttled, or no healthy route right now.	Retry with backoff.
gateway_overloaded	429	The bounded replay window is full.	Retry with backoff.
request_cancelled	499	The client disconnected before completion.	Reissue the request if you still want the result.
all_routes_failed	502	Every provider in the waterfall failed.	Retry; if you are on BYOK, check your provider key.
provider_output_too_large	502	Provider output exceeded the gateway response limit.	Lower max output tokens.
gateway_draining	503	This instance is draining and is not taking new requests.	Retry; the request lands on another instance.
deadline_exceeded	504	The request ran past the gateway deadline.	Shorten the work or retry.
internal_error	500	An unexpected failure.	Retry with backoff.

unsupported_capability and unsupported_parameter are distinct: the first means a whole capability is off the table for this route (it serves no tools, or no reasoning at all), so switch models; the second means the route serves the capability but rejects one field of your request (for example temperature on a reasoning-only route) — drop that field and resend, or pick a model whose Supported parameters include it.

Any unknown /v1 path returns 404 with code=not_found. The gateway serves exactly /v1/models, /v1/chat/completions, and /v1/responses.

What to retry

Retry 429 (throttled or overloaded), 502, 503, and 504 with exponential backoff.
Do not blindly retry 400, 401, 403, or 409. Fix the request first; the same call fails the same way.
insufficient_quota is not transient: it clears when you add credits or raise a limit, not on retry.

Delivery is at-least-once: an ambiguous network failure that you retry can dispatch and bill the underlying provider twice. Pass an Idempotency-Key header so an exact retry replays the original result instead of running again.

Errors

Every error the gateway returns is an OpenAI-compatible envelope with a stable code. The messages are written so an agent can self-correct from the code and message alone.

The error envelope

Every failure on /v1/chat/completions, /v1/responses, and /v1/models returns the same shape, so existing OpenAI error handling keeps working:

{
  "error": {
    "message": "The requested model alias is not granted to this identity.",
    "type": "permission_error",
    "code": "model_not_granted",
    "param": null
  }
}

Branch on code, not the message text; the message is human-readable and may change, the code is stable.

Stable codes

code	HTTP	Meaning	How to recover
model_location_not_supported	403	The request location is outside this model maker's supported regions, or could not be verified.	Choose another model or contact support if the location is incorrect. Retrying, changing keys, or adding credits will not resolve this policy refusal.
invalid_json	400	The request body is not valid JSON.	Fix the request body.
invalid_request	400	The request is malformed.	Read the message, fix the request, and resend.
invalid_parameter	400	A field is invalid; param names it.	Correct that field and resend.
unsupported_capability	400	A whole capability the model route does not expose (a tool, a modality, reasoning) was requested.	Pick a capable model; check supported_params and modalities in /api/models.
unsupported_parameter	400	A specific request parameter the model route rejects (e.g. temperature on a reasoning-only route, or top_k / frequency_penalty / presence_penalty / top_logprobs where the route does not accept them); param names it.	Remove the field, or choose a model whose Supported parameters include it (shown on the model page).
previous_response_not_found	400	previous_response_id is unknown or expired on this worker.	Resend the full conversation instead of continuing.
invalid_key	401	The key is missing, malformed, expired, or revoked.	Fix the Authorization header.
model_not_granted	403	Your organization cannot call this slug.	Use a slug returned by GET /v1/models.
idempotency_conflict	409	The same Idempotency-Key was reused with a different body.	Use a fresh Idempotency-Key.
idempotency_replay_unavailable	409 / 500	The original keyed result is gone after a restart.	Resend with a new Idempotency-Key.
insufficient_quota	429	A spend limit or your credit balance is exhausted; the message says which (a daily org cap, a per-model cap, or credits).	Add credits or raise limits at /credits (platform-funded lane only).
unavailable_route	429 / 503	Throttled, or no healthy route right now.	Retry with backoff.
gateway_overloaded	429	The bounded replay window is full.	Retry with backoff.
request_cancelled	499	The client disconnected before completion.	Reissue the request if you still want the result.
all_routes_failed	502	Every provider in the waterfall failed.	Retry; if you are on BYOK, check your provider key.
provider_output_too_large	502	Provider output exceeded the gateway response limit.	Lower max output tokens.
gateway_draining	503	This instance is draining and is not taking new requests.	Retry; the request lands on another instance.
deadline_exceeded	504	The request ran past the gateway deadline.	Shorten the work or retry.
internal_error	500	An unexpected failure.	Retry with backoff.

Any unknown /v1 path returns 404 with code=not_found. The gateway serves exactly /v1/models, /v1/chat/completions, and /v1/responses.

What to retry

Retry 429 (throttled or overloaded), 502, 503, and 504 with exponential backoff.
Do not blindly retry 400, 401, 403, or 409. Fix the request first; the same call fails the same way.
insufficient_quota is not transient: it clears when you add credits or raise a limit, not on retry.

Errors

The error envelope

Stable codes

What to retry

See also

Errors

The error envelope

Stable codes

What to retry

See also