Error codes

Errors use the OpenAI shape, plus the gateway's request id:

{
  "error": {
    "message": "RPM limit exceeded for key (limit 60/min)",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "request_id": "req_6f1c0d9a2b7e4c3f8a5d1e0b"
  }
}

type mapping: 401 → authentication_error, 403 → permission_error, 429 → rate_limit_error, ≥ 500 → api_error, else invalid_request_error.

Code	HTTP	When
missing_api_key	401	No / empty bearer token
invalid_api_key	401	Unknown key hash
key_revoked	401	Revoked
key_expired	401	Expired
key_inactive	401	Non-active status
key_blocked	403	Blocked key
model_access_denied	403	Model not in the key allowlist
scope_blocked	403	User, team, org or app is blocked
customer_blocked	403	Customer is blocked
guardrail_blocked	403	Pre or post guardrail block
budget_exceeded	429	Key, scope, tag, customer or first-class (Budgets page) budget exhausted
budget_approval_required	429	A first-class budget reached a require-approval threshold or limit
rate_limit_exceeded	429	RPM or TPM window exhausted
invalid_request	400	Bad JSON or missing model
model_not_found	404	The model (and its fallbacks) has no deployments configured
upstream_unavailable	502	Every deployment attempt failed, or every deployment of the model and its fallbacks is disabled
internal_error	500	Key context / DB failure
unhealthy	503	Health / readiness probe failure

Rate-limit messages include the scope: RPM limit exceeded for key (limit N/min), TPM limit exceeded for team (limit N tokens/min). Scopes: key, team, application, customer (chat only).

Budget messages include the entity and spend vs max, for example Budget has been exceeded! Key=<alias> Current cost: X, Max budget: Y.

Request IDs

Every gateway response — success or error, including 401/403/404/429/5xx and streaming responses — carries the request id in two headers, set before the first byte is written:

Header	Value
x-zeallm-request-id	req_ followed by 24 hex characters
X-Request-Id	The same value. OpenAI SDKs read this header, e.g. err.request_id on an APIStatusError in Python
x-client-request-id	Only when the request sent its own X-Request-Id: that value echoed back (up to 128 visible ASCII characters)

The gateway always generates its own id; a client-supplied X-Request-Id is never used as the request id. Error bodies repeat the id as error.request_id, so it is available to clients that only log bodies.

Finding a request in the portal

Open Logs and paste the id into the Request ID filter, or deep-link to /logs?requestId=req_… (see Request Logs). The id is the requestId stored on the request's log entry; logs are written asynchronously, so a request may take a moment to appear.

Chat completions, embeddings and responses calls are logged whether they succeed or fail, including rejections for authentication, model access, budgets, rate limits, guardrails, model_not_found and upstream_unavailable. Requests rejected as malformed (400, e.g. invalid_request) and internal errors before routing are not logged; quote the request id and time to support anyway. /v1/models, cost-event and tokenomics-observation calls carry an id but have no log entry.

Retry-After

Some errors include a Retry-After header: a whole number of seconds (rounded up, at least 1) after which retrying can succeed. OpenAI SDKs honour it when they retry. It is omitted when the gateway does not know when the condition will clear.

Error	Retry-After
429 rate_limit_exceeded	Seconds until the current RPM/TPM window rolls over (1–60). Windows are fixed one-minute windows aligned to the clock minute, shared across gateway replicas when Redis is configured. Omitted when the request's own prompt is larger than the TPM limit: no window will ever admit it, so shorten the prompt or ask for a higher limit.
429 budget_exceeded, budget_approval_required	Seconds until the budget named in the message resets: for key, user, team, org, app, tag and customer budgets, the next reset of a budget with a duration; for first-class budgets, the next period reset or the budget's end date, whichever is first. Omitted for budgets that never reset (for example a max budget without a duration). If the reset time has passed but the reset job (every minute) has not yet applied it, 60.
502 upstream_unavailable	Only when providers answered 429: the gateway does not pass upstream 429s through, it retries other deployments and fallbacks first. If it runs out, it forwards the shortest upstream Retry-After (or retry-after-ms) it received.

An approved budget change request can lift a budget block before Retry-After elapses.