Errors

Current OpenGateway error envelope, error types, retry guidance, and streaming errors for the OpenAI-compatible data plane.

OpenGateway returns errors in OpenAI's envelope no matter which provider served the request. The HTTP status, the error.type, and the human-readable message follow OpenAI's conventions, so existing try/except logic in your SDK keeps working.

Error envelope#

{
  "error": {
    "message": "Rate limit reached for openai/gpt-4o.",
    "type": "rate_limit_error"
  }
}

HTTP status reflects what happened (4xx for caller errors, 5xx for upstream)
error.type is a machine-readable string you can branch on
error.message is human-readable; show it to developers, not end users

Reference#

HTTP	`error.type`	When	What to do
400	`invalid_request_error`	Body malformed, missing required field, unsupported model, or unsupported parameter.	Fix the request. Do not retry unchanged.
401	`authentication_error`	Bad API key or missing `Authorization` header.	Check your key.
403	`permission_denied_error`	Access denied by the gateway.	Contact the team owner.
404	`not_found_error`	A requested resource was not found.	Check the path or model ID.
408	`request_timeout_error`	Request body transmission timed out.	Retry the request.
429	`rate_limit_error`	Upstream provider rate limit.	Retry with exponential backoff, or use fallbacks.
500	`internal_server_error`	Unexpected gateway-side failure.	Retry. If it persists, contact support.
500	`api_error`	All fallback attempts failed or a provider request failed in a way the gateway reports as an API error.	Inspect the logs and routing attempts.
503	`service_unavailable_error`	Upstream provider is down or unreachable.	Retry. Chat fallbacks help here.

When to retry#

Retry-safe errors:

408 request_timeout_error — yes
429 rate_limit_error — yes, with exponential backoff
500 internal_server_error — yes, up to 3 attempts
500 api_error — yes when caused by upstream failure
503 service_unavailable_error — yes

Do not retry:

400 invalid_request_error — the request is wrong; retrying produces the same error
401 authentication_error — the key is wrong
403 permission_denied_error — the team denies access
404 not_found_error — the resource does not exist

Use fallbacks instead of retries#

Most retryable errors disappear if you configure fallbacks. Instead of waiting out a 429 from OpenAI, the gateway tries Anthropic on the same request.

{
  "model": "openai/gpt-4o",
  "extra": {
    "fallbacks": ["anthropic/claude-sonnet-4", "google/gemini-2.5-pro"]
  },
  "messages": [...]
}

When every fallback fails, you receive an api_error response. See Fallbacks for the full policy.

Streaming errors#

Chat streaming errors arrive as a final SSE data chunk:

data: {"error":{"message":"Provider stream interrupted","type":"server_error"}}

data: [DONE]

Treat an error chunk as terminal.

What to know#

How do I know which provider served (or failed) my request?#

Chat Completions responses include extra.routing.attempts. The dashboard also shows provider and model information for every log row.

Do I get billed for failed requests?#

Billing follows the recorded token usage and cost for the request.

Fallbacks

The cleanest way to make most retryable errors disappear.

HTTP Headers

Gateway attribution and correlation headers.

Logs

Find the exact request behind any error code.

Authentication

What 401 and 403 actually check.