响应头与错误码

AISIX 会通过多种面向调用方的 API 格式返回响应。失败的 chat completions 请求、Anthropic 风格 messages 请求、服务提供方透传请求和 Admin 请求使用的错误信封并不相同。

本参考帮助你理解响应头、重试提示、状态码和错误字段。排查时应先确认请求的 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 风格代理错误
/passthrough/:provider/*rest 下的服务提供方透传路由	上游服务提供方状态码和响应体	透传错误
/admin/* 下的 Admin API 路由	{"error_msg":"..."}	Admin 错误信封

代理响应头

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

响应头	使用场景
x-aisix-call-id	出现在 chat completions 响应中，用于关联一次网关调用。
x-aisix-request-id	出现在 messages、responses、rerank、audio 和 passthrough 等直接透传风格端点中，用于关联被代理的请求。
x-aisix-served-by	出现在成功的 chat completions 路由响应中，用于识别实际处理请求的目标模型。
x-aisix-cache	出现在聊天缓存命中或未命中路径中，用于确认响应是否由网关缓存返回。
x-ratelimit-*	当调用方 API Key 配置了限流时，会出现在成功的 chat completions 响应中，用于查看请求、token 和并发限制状态。
Retry-After	当网关能够给出重试提示时，会出现在限流、预算和所有候选不可用的拒绝响应中；当 AISIX 能解析上游 429 的重试提示时，也会透出该响应头。调用方可据此判断重试时间。

代理状态码

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

状态码	含义
400	请求无效。
401	调用方认证缺失或无效。
403	该调用方 API Key 无权访问请求的模型。
404	请求的模型别名未找到。
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	调用方认证缺失或无效。
permission_denied	403	调用方 API Key 有效，但无权使用请求的模型，或调用方客户端 IP 不在模型的 allowed_cidrs 范围内。
model_not_found	404	请求的模型别名未配置。
invalid_request_error	400 或 413	请求体或端点使用方式无效。过大的 OpenAI 风格请求会返回该错误类型和 413 状态码。
provider_unavailable	503	选中的上游服务提供方适配器无法完成请求。
all_candidates_unavailable	503	所有路由候选都被过滤或不可用。
content_filter	422	请求或响应被策略拦截。
billing_error	429	请求被计费或预算状态拒绝。
rate_limit_exceeded	429	请求超过已配置的限流规则。
not_implemented	501	解析出的服务提供方适配器未实现该端点。
timeout	504	上游请求超时。
upstream_error	不固定，上游服务端失败通常为 502	上游服务提供方返回错误，AISIX 将其渲染为代理错误格式。

上游服务提供方错误

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 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
其它状态码	api_error

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

示例参见 Anthropic 风格 Messages API。

透传错误

ANY /passthrough/:provider/*rest 会在完成代理认证和服务提供方解析后，原样转发上游服务提供方的状态码和响应体。参见服务提供方透传。

Admin 错误信封

Admin API 使用如下错误信封：

{
  "error_msg": "..."
}

Admin 状态码如下：

状态码	含义
400	Admin 请求载荷无效。
401	Admin 认证缺失或无效。
404	资源未找到。
409	资源冲突，例如唯一字段重复。
500	网关侧 Admin API 失败。