Headers and Error Codes

AISIX returns responses through several caller-facing API formats. A failed chat-completions request, an Anthropic-style messages request, a provider passthrough request, and an admin request do not all use the same error envelope.

This reference helps interpret response headers, retry hints, status codes, and error fields. Start with the request path, then read the matching error format before deciding whether the failure is caller-side, gateway-side, or upstream-provider-side.

Error Response Formats

Use the request path to identify the error envelope that applies.

Response came from	Error envelope	Read
OpenAI-compatible proxy routes such as /v1/chat/completions, /v1/completions, /v1/embeddings, /v1/responses, audio, images, and rerank	{"error": {...}}	OpenAI-Style Proxy Errors
Anthropic-style proxy routes such as /v1/messages and /v1/messages/count_tokens	{"type":"error","error": {...}}	Anthropic-Style Proxy Errors
Provider passthrough routes under /passthrough/:provider/*rest	Upstream provider status and body	Passthrough Errors
Admin API routes under /admin/*	{"error_msg":"..."}	Admin Error Envelope

Proxy Response Headers

Operational headers vary by endpoint. Do not treat every header as universal across every /v1/* route.

Header	When to use it
x-aisix-call-id	Appears on chat-completions responses. Use it to correlate one gateway call.
x-aisix-request-id	Appears on direct passthrough-style endpoints such as messages, responses, rerank, audio, and passthrough. Use it to correlate the proxied request.
x-aisix-served-by	Appears on successful chat-completions routing responses. Use it to identify the target model that served the request.
x-aisix-cache	Appears on chat cache hit or miss paths. Use it to check whether the gateway served the response from cache.
x-ratelimit-*	Appears on successful chat-completions responses when the caller API key has rate limits configured. Use it to inspect request, token, and concurrent limit state where applicable.
Retry-After	Appears on rate-limit, budget, and all-candidates-unavailable rejections when the gateway has a retry hint. Also appears on upstream 429 responses when AISIX can parse the upstream retry hint. Use it to tell callers when to retry.

Proxy Status Codes

Use the error type first when the envelope includes one. The status code gives the broad category, and the error type usually identifies the more precise gateway condition.

Status	Meaning
400	The request is invalid.
401	Caller authentication is missing or invalid.
403	The model is not allowed for the key.
404	The model alias was not found.
413	The request body exceeds the configured proxy request body limit.
422	Content was blocked by policy.
429	The request hit a rate limit or budget rejection.
501	The resolved provider adapter does not implement the requested endpoint.
502	The upstream provider returned a server-side failure or the provider adapter mapped an upstream failure into the proxy error format.
503	The provider adapter is unavailable, or every routing candidate was filtered out by runtime status.
504	The upstream request timed out.

OpenAI-Style Proxy Errors

AISIX OpenAI-compatible proxy errors use this envelope:

{
  "error": {
    "message": "...",
    "type": "invalid_request_error"
  }
}

The param and code fields are omitted when AISIX has no value for them. Budget denials include structured budget fields inside the error object, such as scope, limit_usd, spent_usd, period, and retry_after_seconds.

Common AISIX error.type values are:

Error type	Typical status	Meaning
invalid_api_key	401	Caller authentication is missing or invalid.
permission_denied	403	The caller API key is valid but cannot use the requested model, or the caller's client IP is outside the model's allowed_cidrs.
model_not_found	404	The requested model alias is not configured.
invalid_request_error	400 or 413	The request body or endpoint usage is invalid. Oversized OpenAI-style requests return this error type with status 413.
provider_unavailable	503	The selected upstream provider adapter cannot complete the request.
all_candidates_unavailable	503	Every routing candidate was filtered out or unavailable.
content_filter	422	The request or response was blocked by policy.
billing_error	429	The request was rejected by billing or budget state.
rate_limit_exceeded	429	The request exceeded a configured rate limit.
not_implemented	501	The resolved provider adapter does not implement the requested endpoint.
timeout	504	The upstream request timed out.
upstream_error	Varies, often 502 for upstream server-side failures	The upstream provider returned an error that AISIX rendered through the proxy error format.

Upstream Provider Errors

OpenAI-style routes render upstream provider failures through the same error envelope, but AISIX does not always return the upstream response unchanged.

Upstream 4xx responses keep the client-visible HTTP class. Native OpenAI upstream errors can keep their OpenAI-style fields. Cross-provider upstream errors use upstream_error and can include a more specific error.code, such as a rate-limit, permission, or model-not-found code.

Upstream 5xx responses generally return 502. AISIX does not expose upstream 5xx response bodies because they can contain provider account, infrastructure, or private diagnostic detail.

Anthropic-Style Proxy Errors

POST /v1/messages and POST /v1/messages/count_tokens use the Anthropic-style error envelope:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "..."
  }
}

The Anthropic envelope omits the param and code fields that the OpenAI envelope can carry.

The nested error.type follows Anthropic SDK-compatible status mappings:

Status	Anthropic error.type
400 or 422	invalid_request_error
401	authentication_error
403	permission_error
404	not_found_error
408	timeout_error
413	request_too_large
429	rate_limit_error
503	overloaded_error
Other status codes	api_error

AISIX keeps the 408 mapping for Anthropic SDK compatibility. Gateway-originated timeouts usually surface through provider-error handling rather than as a native 408 response.

See Anthropic-Style Messages API for examples.

Passthrough Errors

ANY /passthrough/:provider/*rest forwards the upstream provider's status code and body unchanged after proxy authentication and provider resolution. See Provider Passthrough.

Admin Error Envelope

The admin API uses this envelope:

{
  "error_msg": "..."
}

Admin status codes are:

Status	Meaning
400	The admin payload is invalid.
401	Admin authentication is missing or invalid.
404	The resource was not found.
409	A resource conflict, such as a duplicate unique field.
500	A gateway-side admin API failure.