代理错误与重试

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

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

财务预算拒绝仅适用于 AISIX Cloud。下文所述的重试预算是独立的网关设置，用于控制上游失败后的尝试次数。

匹配响应格式

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

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

判断重试是否有帮助

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

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

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

使用重试信号

对于网关限流、预算拒绝、临时不可用路由候选，以及包含重试提示的上游限流响应，AISIX 可以返回 Retry-After。网关限流拒绝一定会带上该响应头，并在 X-RateLimit-Reset 上再次给出相同的延迟，同时说明是哪条限制拒绝了请求；参见限流拒绝响应头。

当该响应头存在时，请将其作为主要延迟。如果客户端 SDK 也有自动重试，优先使用 AISIX 或上游服务提供方给出的延迟，而不是固定本地间隔。只要延迟足够短、不会超出调用方请求，AISIX 在安排自身重试时也会遵循服务提供方返回的 Retry-After。

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

区分网关故障转移与客户端重试

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

• retries 会在可重试失败后对同一个已选目标重复尝试，并逐步增加尝试间隔。它适用于重试预算中列出的推理路由，但不适用于 Realtime、透传路由，也不适用于文件、批处理和微调 API。
• 流式请求只能在 AISIX 向调用方提交响应字节前故障转移。AISIX 仍在建立上游流时，可以执行同目标重试和故障转移；首批字节到达调用方后，后续故障会终止响应。
• max_fallbacks 限制 AISIX 可以尝试的其他目标数量。
• retry_on_429 让上游限流响应进入下一次尝试。
• fallback_on_statuses 对配置的服务提供方特定临时状态码执行相同行为。

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

理解上游故障

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

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

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

检查常见原因

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

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

下一步

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