跳到主要内容

代理错误与重试

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

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

匹配响应格式​

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

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

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

判断重试是否有帮助​

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

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

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

使用重试信号​

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

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

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

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

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

  • Messages、Responses 和非流式 Chat Completions 中，retries 会在可重试失败后重复尝试同一目标。
  • 流式 Chat Completions 对每个符合条件的目标最多尝试一次，并且只能在 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 和上游服务提供方可用性。
所有路由候选不可用检查多目标模型的目标模型运行时状态和服务提供方健康状态。

下一步​

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