代理错误与重试

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

本指南说明客户端侧处理模型。它不能替代完整的响应头与错误码参考，后者列出了精确错误信封、响应头和状态码映射。

匹配响应格式

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

路由族	错误格式	客户端处理
OpenAI 兼容路由，包括 chat completions、embeddings、responses、audio、images 和 rerank	OpenAI 风格错误信封	读取 OpenAI 风格错误类型和可选错误代码。
Anthropic 风格路由，包括 Messages 和 Count Tokens	Anthropic 风格错误信封	读取 Anthropic 风格错误类型。
服务提供方透传路由	上游服务提供方状态码和响应体	AISIX 认证调用方并解析服务提供方目标后，使用服务提供方原生错误处理。

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

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

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

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

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

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

流式响应会改变重试决策。流式请求可能在流开始前失败，但 AISIX 不会在流开始后故障转移。只有当应用可以安全重放 prompt 并处理重复输出风险时，才重试流式请求。

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

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

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

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

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

你已经了解如何分类 AISIX 代理错误和重试信号。精确信封、响应头和状态映射请参见响应头与错误码。服务提供方和端点支持请参见服务提供方兼容性。