Error codes

Error envelopes vary by endpoint family. LLM upstream errors are classified by the readable error message. Only pool-style infrastructure failures that the upstream returns with a non-2xx status are normalized to HTTP 424 so provider details and internal addresses are not exposed. Other upstream non-2xx errors keep the upstream status and retain their public semantics in the protocol-specific envelope (type is upstream_error when the upstream gives none; a non-JSON upstream body is not exposed, and message becomes bad response status code <status> with type and code set to bad_response_status_code; Anthropic Messages appends (request id: …) to message). For an error the upstream returns in an HTTP 200 body (for streams, an error event before any content): streaming OpenAI Chat Completions and Responses requests and native Gemini endpoints receive the upstream HTTP 200 and body unchanged; non-streaming OpenAI Chat Completions and Responses requests receive HTTP 200 with {"error": {...}}; Anthropic Messages returns HTTP 500. When you receive HTTP 200, check the body or stream for error.

LLM and Responses endpoints

Gateway-generated errors normally use:

{
  "error": {
    "message": "Missing model",
    "type": "model_not_found"
  }
}

Common types include invalid_request_error, model_not_found, authentication_error, insufficient_quota, rate_limit_error, api_error, and internal_error.

HTTP 402 (insufficient_quota) states the reason in code:

When an LLM upstream reports a pool-style infrastructure failure, the gateway returns HTTP 424 and a neutral error for the calling protocol. Model identifiers in otherwise public error messages are always reported as the public model ID. OpenAI Chat Completions and Responses use:

{
  "error": {
    "code": "provider_error",
    "message": "Provider error (request id: aitk-12345678)",
    "type": "api_error"
  }
}

Anthropic Messages uses { "type": "error", "error": { "type": "api_error", "message": "..." } }; Gemini uses { "error": { "code": 424, "message": "...", "status": "FAILED_PRECONDITION" } }. Diagnostics for pool failures are retained only in server-side logs. Network failures and stream read failures use the same neutral provider error; a stream emits it as a protocol-specific terminal SSE event.

Other upstream non-2xx errors (including non-JSON bodies, upstream 401/402/403, rate limits, and 5xx) keep the upstream HTTP status. OpenAI Chat Completions and Responses preserve message and any supported type, code, and param fields; Anthropic returns its native error envelope; Gemini returns its native { "error": { "code", "message", "status" } } envelope. Malformed, empty, or otherwise unstructured bodies use a safe protocol-compatible fallback with a redacted message.

Async media task endpoints

Route-level errors from /v1/router/... normally use:

{
  "code": 402,
  "message": "Insufficient balance. Top up to continue.",
  "task_id": ""
}

Media task endpoints do not use the LLM account limits or the retired shared per-key/per-IP allowance.

OpenAI-compatible image endpoints

/v1/images/generations and /v1/images/edits use:

{
  "error": {
    "message": "Only n=1 is supported",
    "type": "invalid_request_error",
    "code": null
  }
}

They may also return authentication_error, insufficient_quota, rate_limit_error, api_error, or timeout_error.

HTTP status reference