代理错误与重试

应用应按一致顺序处理 AISIX 代理失败：先匹配响应格式，再判断重试是否有帮助；如果失败持续存在，再检查路由、策略或上游状态。

本页侧重客户端行为。精确错误信封、响应头和状态码映射请参见响应头与错误码。

匹配响应格式

请先将响应与应用调用的代理路由匹配起来。这样客户端才能知道应读取哪些错误字段，再决定是修正请求、退避还是重试。

路由族	错误格式	客户端处理
OpenAI 兼容路由，包括 Chat Completions、embeddings、responses、audio、images 和 rerank	OpenAI 风格错误信封	读取 OpenAI 风格错误类型和可选错误代码。
Anthropic 风格路由，包括 Messages 和 Count Tokens	Anthropic 风格错误信封	读取 Anthropic 风格错误类型。
服务提供方透传路由	转发上游状态码和响应体；网关生成的失败使用 OpenAI 风格错误信封	AISIX 认证并授权调用方、解析服务提供方模型后，对转发的上游响应使用服务提供方原生处理，对网关生成的失败使用 OpenAI 风格处理。

请将代理错误处理和 Admin 错误处理分开。Admin API 有自己的错误格式，面向管理客户端，而不是应用流量。

当客户端知道收到哪种响应格式后，应将错误类型作为主要决策信号。状态码给出大类，但错误类型通常更能说明应用下一步该做什么。

失败类型	常见原因	重试建议
调用方或配置错误	调用方 API Key、模型别名、访问规则、请求体或端点选择无效。	在请求或网关配置变化前不要重试。
策略拒绝	安全护栏、限流或预算检查拒绝了请求。	响应包含重试提示时退避，否则修改请求或策略。
不支持的路由	解析出的服务提供方适配器未实现请求端点。	选择受支持端点、服务提供方、适配器或模型。
上游失败	上游服务提供方返回错误，AISIX 将其渲染为面向调用方的格式。	仅当失败是临时性的且请求可安全重复时重试。
运行时目标状态	选中目标或所有路由候选临时不可用。	有重试提示时遵循提示；如果状态持续存在，请检查服务提供方健康状态。

请将认证、授权、模型未找到、请求无效和不支持路由错误视为不可重试。限流、带重试提示的预算拒绝、临时上游失败和不可用路由候选可视情况重试。

对于网关限流、预算拒绝、临时不可用路由候选，以及包含重试提示的上游限流响应，AISIX 可以返回 Retry-After。

当该响应头存在时，请将其作为主要延迟。如果客户端 SDK 也有自动重试，优先使用 AISIX 或上游服务提供方给出的延迟，而不是固定本地间隔。

流式响应会改变重试决策。请求可以在流开始前故障转移，但响应字节到达调用方后，AISIX 不会再进行故障转移。只有当应用可以安全重放提示词并处理重复输出风险时，才重试流式请求。

对于多目标模型，AISIX 可以在向应用返回错误前执行额外尝试。网关行为独立于应用或 SDK 的重试策略：

retries 会在可重试失败后重复尝试同一目标，并在尝试之间执行指数退避。Messages、Responses 和 Chat Completions 的流式及非流式请求均适用。
流式请求只能在 AISIX 向调用方提交响应字节前故障转移。AISIX 仍在建立上游流时，可以执行同目标重试和故障转移；首批字节到达调用方后，后续故障会终止响应。
max_fallbacks 限制 AISIX 可以尝试的其它目标数量。
retry_on_429 让上游限流响应进入下一次尝试。
fallback_on_statuses 对配置的服务提供方特定临时状态码执行相同行为。

Count Tokens 可以跨符合条件的目标故障转移，但目前不会重复尝试同一目标。

应用只会在网关处理结束后，或失败不符合网关重试条件时看到错误。配置两层激进重试前，请考虑组合后的上游尝试总数。网关配置请参见路由与故障转移。

部分失败来自 AISIX，发生在调用上游之前。其它失败来自选中的上游服务提供方，并通过面向调用方的代理格式渲染。

对于上游 4xx 失败，AISIX 会保持面向调用方的响应格式。在 OpenAI 风格路由上，跨服务提供方上游失败会使用稳定的 upstream_error 类型，并可能包含更具体的代码，例如限流、权限或模型未找到代码。原生 OpenAI 上游失败可以保留更多 OpenAI 风格错误字段。

对于上游 5xx 失败，AISIX 通常返回 502，且不暴露上游响应体。上游服务器错误可能包含服务提供方账号、基础设施或内部诊断细节，因此更深入诊断应使用网关日志。

可以使用以下检查判断失败源自调用方请求、网关配置、策略、路由状态还是上游服务提供方。

现象	检查项
认证失败	确认应用发送的是明文调用方 API Key，而不是已存储的密钥哈希或上游服务提供方密钥。
权限失败	确认调用方 API Key 允许请求的模型别名。
模型未找到	确认应用发送的是面向调用方的模型别名，而不是上游服务提供方模型 ID。
限流或预算拒绝	检查调用方 API Key 限制、模型限制、匹配的限流策略和托管预算状态。
不支持的端点	确认选中的服务提供方和适配器支持应用调用的路由。
某个模型别名返回 `502`	检查该别名的上游调用路径、服务提供方凭证、base URL 和上游服务提供方可用性。
所有路由候选不可用	检查多目标模型的目标模型运行时状态和服务提供方健康状态。

精确响应字段请参见响应头与错误码；当失败取决于端点或适配器支持情况时，请参见服务提供方兼容性。