Errors

Every error Gateway returns, in one place

Gateway errors share one JSON envelope, carry a stable code you can branch on, and tell you whether the failure came from Gateway or from the upstream provider. This page is the aggregate reference; each feature page covers its own errors in context.

The error envelope

Model API errors (/v1/responses and every compatible surface) return:

1{
2  "error": {
3    "type": "invalid_request_error",
4    "message": "Project budget exceeded for '4f8b2c6e-9d1a-4e7a-b3f5-2c8d0a6e1b47'.",
5    "code": "project_budget_exceeded",
6    "param": "project_id",
7    "source": "gateway",
8    "provider": null
9  }
10}
  • type is the broad category (invalid_request_error, authentication_error, budget_exceeded, blocked_by_policy, rate_limit_error, not_found_error, provider_error, internal_error).
  • code is the specific, stable identifier. Branch on code, not on message text.
  • source is "gateway" when Gateway rejected the request itself and "provider" when the upstream provider failed; provider then names the vendor.

The Management API (/v1/keys, /v1/projects, /v1/routing-policies, /v1/customers) uses FastAPI’s {"detail": ...} shape instead, with structured codes on the cases worth branching on (for example 409 PROJECT_HAS_ACTIVE_API_KEYS).

Authentication: 401

codeMeaning
(none, invalid_request_error)Missing key, or a malformed Authorization header
invalid_api_keyKey unknown, expired, or inactive; also a management key used on model endpoints, or a model key used on /v1/keys

Payment and budgets: 402

codeScopeFix
budget_exceededOrganization credit balanceAdd credits, or upgrade off the free tier
payment_failedOrganization payment stateUpdate the payment method
project_budget_exceededProject hard limitRaise the project budget (changes take up to an hour to apply)
api_key_limit_exceededPer-key spend limitRaise limit or wait for the limit_reset window
(none, budget_exceeded)Embedded Routing customer budgetRaise the customer’s budget

Responses include remaining-headroom headers as limits approach: X-Credit-Balance-USD, X-Project-Budget-Remaining-USD / X-Project-Budget-Limit-USD, X-Key-Limit-Remaining-USD / X-Key-Limit-USD.

Invalid requests: 400

codeMeaning
model_requiredNo model and no routing policy resolved (or the resolved policy has no providers)
invalid_model_formatThe model string matched nothing; use provider/model
ambiguous_base_modelA bare model name matched several providers; qualify it
project_mismatchThe request’s project_id conflicts with a project-scoped key
unsupported_paramsThe chosen route can’t serve the request (tool calling, structured outputs, an input modality, or the requested service_tier)
capability_unavailableNo vendor for the model supports the requested capabilities
context_window_exceededProvider rejected the request as too large (source: "provider")
content_policy_violationProvider’s content policy blocked the request (source: "provider")
zdr_vendor_unavailableZero data retention is on and no ZDR-compliant vendor serves the model
fusion_config_required, fusion_stream_unsupported, fusion_unsupported_tools, fusion_routing_policy_unsupportedFusion constraints
web_search_unavailable, unsupported_web_search_engine, invalid_server_tool_parameters, server_tool_iteration_limit_exceededWeb search constraints
unknown_tagsA tag not defined for your org; list them with GET /v1/tags

Policy and permission blocks: 403 and 422

StatuscodeMeaning
403customer_blocked, customer_pinned, customer_model_blocked, provider_blocked, model_blockedA blocklist rule matched; type is blocked_by_policy
422blocked_by_dlp_policyA DLP rule blocked the request
422pi_block_threshold and related pi_* codesPrompt injection protection blocked the request; type is blocked_by_pi_protection

Not found: 404

model_not_found (check GET /v1/models), vendor_not_found, and customer_not_found (Embedded Routing).

Too large and too fast: 413 and 429

StatuscodeMeaning
413payload_too_largeInline base64 media over the per-modality cap (20 MB; 25 MB for audio). Send a URL reference instead
429(none, rate_limit_error, source: "provider")The upstream provider throttled the request. With a routing policy, this triggers failover before you ever see it
429(none, rate_limit_error, source: "gateway")A Gateway-enforced limit; the response carries Retry-After. See Rate limits

Provider failures: 5xx

codeMeaning
provider_authentication_failed (502)The credentials serving the route were rejected upstream; for BYOK, check your provider key
provider_account_restricted (502)The provider declined for account or billing reasons on the serving credentials
(none, 502)Transient provider failure or timeout. Retry, or let a Priority policy fail over
model_vendor_unhealthy (502)Gateway’s circuit breaker has the route marked unhealthy after repeated failures
internal_error (500)Unexpected Gateway error; retry, and contact support if it persists

Provider failures (429, 5xx, timeouts) trigger routing-policy failover automatically; client errors (400 to 404) do not.

Errors during streaming

Once a stream starts, the HTTP status is already 200, so failures arrive as in-stream frames: response.error on the native API, a response.failed event on the OpenAI Responses surface, and an Anthropic-shaped error event on the Anthropic surface. See Streaming for each surface’s exact contract.

Next steps

Rate limits

What Gateway enforces, what providers enforce, and how to handle 429s

Streaming

The wire contract per surface, including mid-stream errors

Routing policies

Turn provider failures into automatic failover