API reference

Errors

Use the stable gateway code to decide what to fix or retry.

Error envelope

JSON errors contain error.message, error.type and error.code. The response also includes x-gateway-error-code. Raw provider error text is not exposed in gateway-generated JSON errors.

{
  "error": {
    "message": "API key invalid, expired, or revoked.",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}

Status codes

HTTP	Code	Type	Action / cause
401	`missing_api_key`	`authentication_error`	Send Authorization: Bearer or x-api-key.
401	`invalid_api_key`	`authentication_error`	Check the key is active; replace a revoked key.
402	`quota_exhausted`	`invalid_request_error`	Add account credit; do not automatically retry.
403	`permission_denied`	`permission_error`	Complete required Telegram verification in the dashboard.
404	`invalid_model`	`invalid_request_error`	Choose an enabled model or exact alias; upstream 404 also maps here.
400	`invalid_json`	`invalid_request_error`	Fix malformed JSON.
400	`bad_request`	`invalid_request_error`	Upstream rejected the request; check endpoint-specific fields.
413	`payload_too_large`	`invalid_request_error`	Reduce the body below the 25 MB parser limit.
429	`rate_limit_exceeded`	`rate_limit_error`	Per-user throttle, rolling plan allowance or upstream rate limit.
502	`upstream_error`	`api_error`	Provider/network failure; upstream 401/403 are sanitized to this code.
503	`service_unavailable`	`api_error`	No usable provider or upstream service unavailable.
504	`gateway_timeout`	`api_error`	Timeout reaching a provider (120-second upstream request timeout).
500	`internal_error`	`api_error`	Unexpected gateway failure.
404	`not_found`	`invalid_request_error`	No such gateway route.

context_length_exceeded and content_policy_violation are defined error types in the backend catalogue, but the current inference proxy maps generic upstream HTTP 400 to bad_request; it does not inspect provider text to distinguish these cases.

Retry safely

For transient 429 and 5xx, use bounded exponential backoff with jitter. Honor Retry-After when supplied by the per-minute throttle; plan and upstream errors do not guarantee that header. Avoid retrying authentication, insufficient-credit and malformed-input errors unchanged.

Provider failover already happens on network errors, upstream 429 and upstream 5xx before a successful response. Ordinary upstream 4xx do not trigger failover. No idempotency mechanism is implemented for inference: retrying after an uncertain result can create another request and charge.

After a stream starts

HTTP status cannot change after HTTP 200. Handle SSE error events and incomplete output separately from JSON errors.