响应头与错误码

AISIX 会通过多种面向调用方的 API 格式返回响应。失败的 Chat Completions 请求、Anthropic 风格 Messages 请求和透传路由请求使用的错误信封并不完全相同。

本参考帮助你理解响应头、重试提示、状态码和错误字段。排查时应先确认请求的 URL 路径，再查看对应错误格式，然后判断失败来自调用方、网关侧还是上游服务提供方。

错误响应格式

请根据请求的 URL 路径识别适用的错误信封。

响应来源	错误信封	阅读
OpenAI 兼容代理路由，例如 /v1/chat/completions、/v1/completions、/v1/embeddings、/v1/responses、音频、图像和 rerank	{"error": {...}}	OpenAI 风格代理错误
Anthropic 风格代理路由，例如 /v1/messages 和 /v1/messages/count_tokens	{"type":"error","error": {...}}	Anthropic 风格代理错误
/mcp 和 /mcp/{server} 下的 MCP 路由	JSON-RPC 错误信封	MCP 错误
/a2a/{agent} 下的 A2A 调用	上游 JSON-RPC 响应；转发前失败使用 HTTP 错误；上游分发失败使用 JSON-RPC 错误	A2A 错误
/a2a/{agent}/.well-known/agent-card.json 下的 A2A Agent Card	成功时使用 Agent Card JSON；网关或上游失败时使用 HTTP 错误响应	A2A 错误
已配置的透传路由	转发上游状态码和响应体；AISIX 生成的失败使用 {"error": {...}}	透传错误

代理响应头

运行时响应头会因端点而异，不应假设每个响应头都适用于所有 /v1/* 路由。

响应头	使用场景
x-aisix-call-id	出现在 Chat Completions 响应中，用于关联一次网关调用。
x-aisix-request-id	出现在每个代理响应中，用于将响应与对应的访问日志和用量事件关联起来。该请求头默认在请求上同样被接受：发送你自己的 ID，AISIX 会全程使用该值而不再自行生成。从哪些请求头读取 ID 可配置，因此具体部署可以扩展或关闭该行为。参见复用自己的请求 ID。
x-aisix-served-by	出现在成功的 Chat Completions 路由响应中，用于识别实际处理请求的目标模型。
x-aisix-cache	出现在缓存策略覆盖的聊天请求上：hit、miss 或 bypass（调用方发送了 Cache-Control: no-cache 或 no-store）。用于确认响应是否由网关缓存返回。
x-aisix-cache-layer	出现在缓存命中时：完全相同请求的匹配为 exact，向量相似度匹配为 semantic。用于区分命中来自哪个匹配层。
x-aisix-cache-similarity	出现在语义缓存命中时。匹配条目的余弦相似度，取值 0–1。用于校准策略的相似度阈值。
x-ratelimit-*	当调用方 API Key 配置了限流时，会出现在成功的 Chat Completions 响应中，用于查看请求、Token 和并发限制状态。
Retry-After	当网关能够给出重试提示时，会出现在限流、预算和所有候选不可用的拒绝响应中；当 AISIX 能解析上游 429 的重试提示时，也会透出该响应头。调用方可据此判断重试时间。

代理状态码

当错误信封包含 error type 时，应优先查看它。状态码给出大类，error type 通常能标识更精确的网关状态。

状态码	含义
400	请求无效。
401	调用方认证缺失或无效。
403	调用方已通过身份认证，但已配置的访问控制不允许该请求。
404	请求的资源未找到。网关生成的示例包括未知模型别名、MCP 服务器或 A2A Agent。上游服务也可能返回 404；AISIX 会保留上游 4xx 状态码。
413	请求体超过代理请求体大小限制。
422	内容被策略拦截。
429	请求触发限流或预算拒绝。
501	解析出的服务提供方适配器未实现该端点。
502	上游服务提供方返回服务端失败，或适配器将上游失败映射为代理错误格式。
503	身份认证依赖项或服务提供方适配器不可用，或所有路由候选都被运行时状态过滤。
504	上游请求超时。

OpenAI 风格代理错误

AISIX 的 OpenAI 兼容代理错误使用如下信封：

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

当 AISIX 没有对应值时，会省略 param 和 code 字段。预算拒绝会在 error 对象中包含结构化预算字段，例如 scope、limit_usd、spent_usd、period 和 retry_after_seconds。

常见的 AISIX error.type 取值如下：

错误类型	常见状态码	含义
invalid_api_key	401	调用方认证缺失或无效。无效、已过期或未映射的 JWT 也使用此类型；具体情况请检查 error.code。
permission_denied	403	调用方 API Key 无权使用请求的模型、调用方客户端 IP 不在模型的 allowed_cidrs 范围内，或已验证的 JWT 不满足必需 Scope 或 Claim。
model_not_found	404	请求的模型别名未配置。
invalid_request_error	400 或 413	请求体或端点使用方式无效。过大的 OpenAI 风格请求会返回该错误类型和 413 状态码。
provider_unavailable	503	选中的上游服务提供方适配器无法完成请求。
all_candidates_unavailable	503	所有路由候选都被过滤或不可用。
api_error	503	AISIX 无法完成内部依赖操作，例如获取用于 JWT 身份认证的签名密钥。
content_filter	422	请求或响应被策略拦截。
billing_error	429	请求被计费或预算状态拒绝。
rate_limit_exceeded	429	请求超过已配置的限流规则。
not_implemented	501	解析出的服务提供方适配器未实现该端点。
timeout	504	上游请求超时。
upstream_error	不固定，上游服务端失败通常为 502	上游服务提供方返回错误，AISIX 将其渲染为代理错误格式。

身份认证错误码

OpenAI 风格代理错误可能包含以下用于调用方身份认证的稳定 error.code 值。Anthropic 风格代理错误会省略 code；请改用其 HTTP 状态码和按状态映射的 error.type。

error.code	状态码	含义
api_key_expired	401	调用方 API Key 的到期时间已过。
api_key_disabled	401	调用方 API Key 已被管理员禁用。
jwt_invalid	401	JWT 格式错误，或未通过签发者、签名、签名算法、受众、必需 Claim 或生效时间验证。
jwt_expired	401	JWT 的 exp 到期时间已过。
jwt_claims_rejected	403	JWT 有效，但不满足信任提供方要求的 Scope 或绑定 Claim。
jwt_identity_unmapped	401	缺少已配置的身份 Claim，或该 Claim 未映射到绑定此 OIDC 提供方的调用方 API Key。
jwks_unavailable	503	AISIX 无法解析或获取信任提供方的签名密钥。请检查 OIDC Discovery 或 JWKS 端点，然后重试。

有关 JWT 信任提供方配置和拒绝行为，请参阅 JWT 身份认证。

上游服务提供方错误

OpenAI 风格路由会通过同一错误信封渲染上游服务提供方失败，但 AISIX 不一定原样返回上游响应。

上游 4xx 响应会保留客户端可见的 HTTP 类别。原生 OpenAI 上游错误可以保留 OpenAI 风格字段。跨服务提供方上游错误会使用 upstream_error，并可能包含更具体的 error.code，例如限流、权限或模型未找到代码。

上游 5xx 响应通常会返回 502。AISIX 不暴露上游 5xx 响应体，因为其中可能包含服务提供方账号、基础设施或私有诊断信息。

Anthropic 风格代理错误

POST /v1/messages 和 POST /v1/messages/count_tokens 使用 Anthropic 风格错误信封：

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

Anthropic 信封会省略 OpenAI 信封可能携带的 param 和 code 字段。

嵌套的 error.type 遵循与 Anthropic SDK 兼容的状态映射：

状态码	Anthropic error.type
400 或 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
其它状态码	api_error

AISIX 保留 408 映射以兼容 Anthropic SDK。网关侧产生的超时通常会通过服务提供方错误处理暴露，而不是作为原生 408 响应返回。

示例参见 Anthropic 风格 Messages API。

MCP 错误

ANY /mcp 和 ANY /mcp/{server} 使用 MCP Streamable HTTP 和 JSON-RPC 响应结构。身份认证失败或请求体过大等错误仍可能在 MCP 处理程序运行前使用 401 或 413 等 HTTP 状态码。

当安全护栏阻断工具调用或工具结果时，AISIX 会返回 HTTP 200，并在响应体中返回标记了 isError 的工具结果。MCP 把 JSON-RPC 协议错误保留给不合法的请求；策略拒绝属于工具执行失败，因此调用方 Agent 会把它当作工具输出读取并据此调整：

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": {
    "content": [{ "type": "text", "text": "tool call blocked by content policy (guardrail 'block-secrets')" }],
    "isError": true
  }
}

这与 OpenAI 兼容路由不同，后者的安全护栏拦截使用 HTTP 422 和 OpenAI 风格错误信封。

被拒绝或不存在的工具则仍然是协议错误——HTTP 200 且 error.code 为 -32602——因为此时请求本身指定了调用方无权调用的对象。

A2A 错误

POST /a2a/{agent} 会原样返回成功的上游 JSON-RPC 响应。网关识别 Agent 并进入 A2A 分发后，如果上游连接失败或返回非成功响应，则会返回 HTTP 502 和 JSON-RPC 错误信封：

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

部分失败发生在 AISIX 转发 A2A 请求之前，因此不使用 JSON-RPC 错误。调用方身份认证缺失或无效时返回 401；调用方 Key 无权访问已注册 Agent 时返回 403；Agent 未知或已禁用时返回 404。限流或 AISIX Cloud 预算拒绝返回 429。

Agent Card 发现使用普通 HTTP 状态码，而不是 JSON-RPC 信封。调用方身份认证缺失或无效时返回 401，Agent 访问被拒绝时返回 403，Agent 未知或已禁用时返回 404。如果网关无法从上游 Agent 获取可用的 Agent Card，则返回 502。如果网关无法从请求中确定自身的对外地址，则返回 500，而不是返回一份仍然公布上游 Agent 地址的 Agent Card。

流式方法（message/stream、tasks/resubscribe）只在流建立之前遵循上述规则。响应一旦开始，状态行已经发出，之后的上游失败便无法再变成 502：网关会把 JSON-RPC 错误信封作为流的最后一个事件转发，并在用量事件中记录该失败。如果上游对流式调用返回的是普通 JSON-RPC 响应而非流，该响应会作为单个事件转发。

透传错误

当 AISIX 收到上游 HTTP 响应且没有网关策略替换该响应时，命中的透传路由会原样转发上游的状态码和响应体。

AISIX 生成的失败会使用 OpenAI 风格代理错误信封，包括调用方身份认证拒绝、缺少 allowed_routes 授权或来源不在路由 source_cidrs 内（403，来源拒绝携带 error.code: ip_restricted）、护栏阻断（422），以及上游传输、超时或响应解码失败。

没有任何路由认领的 /passthrough/* 路径返回 410，携带稳定的 error.code: endpoint_removed——这是已移除隐式通道的迁移信号。把该路径重建为显式路由即可重新启用。