Headers and Error Codes

AISIX returns responses through several caller-facing API formats. A failed chat-completions request, an Anthropic-style messages request, and a provider passthrough 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
MCP routes under /mcp and /mcp/{server}	JSON-RPC error envelope	MCP Errors
A2A calls under /a2a/{agent}	Upstream JSON-RPC response; HTTP errors before forwarding; JSON-RPC error for an upstream dispatch failure	A2A Errors
A2A agent cards under /a2a/{agent}/.well-known/agent-card.json	Agent-card JSON on success; HTTP error response on gateway or upstream failure	A2A Errors
Provider passthrough routes under /passthrough/:provider/*rest	Forwarded upstream status and body, or {"error": {...}} for AISIX-generated failures	Passthrough Errors

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 every proxy response. Use it to correlate the response with its access log and usage event. Accepted on the request by default: send your own ID and AISIX uses that value throughout instead of generating one. Which request headers an ID is read from is configurable, so a deployment can extend or disable this. See Reuse Your Own Request ID.
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 requests covered by a cache policy: hit, miss, or bypass (the caller sent Cache-Control: no-cache or no-store). Use it to check whether the gateway served the response from cache.
x-aisix-cache-layer	Appears on cache hits: exact for an identical-request match, semantic for an embedding-similarity match. Use it to attribute hits between the two matching layers.
x-aisix-cache-similarity	Appears on semantic cache hits. The cosine similarity of the matched entry, 0–1. Use it to calibrate a policy's similarity threshold.
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 caller is authenticated but is not permitted by the configured access controls.
404	The requested resource was not found. Gateway-generated examples include an unknown model alias, MCP server, or A2A agent. An upstream service can also return 404; AISIX preserves upstream 4xx statuses.
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	An authentication dependency or 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. This type also covers an invalid, expired, or unmapped JWT; inspect error.code for the specific condition.
permission_denied	403	The caller API key cannot use the requested model, the caller's client IP is outside the model's allowed_cidrs, or a verified JWT does not satisfy required scopes or claims.
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.
api_error	503	AISIX could not complete an internal dependency operation, such as fetching signing keys for JWT authentication.
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.

Authentication Error Codes

OpenAI-style proxy errors can include these stable error.code values for caller authentication. Anthropic-style proxy errors omit code; use their HTTP status and status-mapped error.type instead.

error.code	Status	Meaning
api_key_expired	401	The caller API key's expiration deadline has passed.
api_key_disabled	401	The caller API key is administratively disabled.
jwt_invalid	401	The JWT is malformed or fails issuer, signature, signing algorithm, audience, required-claim, or not-before validation.
jwt_expired	401	The JWT's exp deadline has passed.
jwt_claims_rejected	403	The JWT is valid but does not satisfy the provider's required scopes or bound claims.
jwt_identity_unmapped	401	The configured identity claim is missing or does not map to a caller API key bound to that OIDC provider.
jwks_unavailable	503	AISIX could not resolve or fetch the provider's signing keys. Check the OIDC discovery or JWKS endpoint, then retry.

For JWT trust-provider configuration and rejection behavior, see JWT Authentication.

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.

MCP Errors

ANY /mcp and ANY /mcp/{server} use MCP Streamable HTTP and JSON-RPC response shapes. Authentication and request-size failures can still use HTTP status codes such as 401 or 413 before the MCP handler runs.

When a guardrail blocks a tool call or tool result, AISIX returns HTTP 200 with a JSON-RPC error envelope. MCP clients can then handle the failure through the protocol response:

{
  "jsonrpc": "2.0",
  "id": 42,
  "error": {
    "code": -32600,
    "message": "..."
  }
}

This differs from OpenAI-compatible routes, where guardrail blocks use HTTP 422 with an OpenAI-style error envelope.

A2A Errors

POST /a2a/{agent} returns a successful upstream JSON-RPC response unchanged. After the gateway has identified the agent and entered A2A dispatch, an upstream connection failure or non-success response returns HTTP 502 with a JSON-RPC error envelope:

{
  "jsonrpc": "2.0",
  "id": 42,
  "error": {
    "code": -32000,
    "message": "..."
  }
}

Some failures occur before AISIX forwards the A2A request and therefore are not JSON-RPC errors. Missing or invalid caller authentication returns 401. A caller key without access to the registered agent returns 403, and an unknown or disabled agent returns 404. Rate-limit or AISIX Cloud budget rejections return 429.

Agent-card discovery uses ordinary HTTP status codes rather than a JSON-RPC envelope. Missing or invalid caller authentication returns 401, and an agent access denial returns 403. An unknown or disabled agent returns 404. If the gateway cannot fetch a usable card from the upstream agent, it returns 502. If the gateway cannot determine its own public address from the request, it returns 500 rather than a card that still advertises the upstream agent's address.

A streaming method (message/stream, tasks/resubscribe) follows the same rules only until the stream opens. Once the response has started, the status line is already sent, so a later upstream failure cannot become a 502: the gateway relays a JSON-RPC error envelope as the final event of the stream instead, and records the failure on the usage event. An upstream that answers a streaming call with a plain JSON-RPC response rather than a stream has that response relayed as a single event.

Passthrough Errors

ANY /passthrough/:provider/*rest forwards the upstream provider's status code and body unchanged when AISIX receives an upstream HTTP response and no gateway policy replaces it.

Failures generated by AISIX use the OpenAI-style proxy error envelope. These failures include caller authentication or authorization rejection, provider-model resolution failure, a guardrail block, and an upstream transport, timeout, or response-decoding failure. See Provider Passthrough.