API 错误 529“过载”：重试、退避和回退策略

如果你的生产日志显示 529 overloaded_error，这意味着服务提供商在告诉你 API 暂时过载。在 Anthropic 的 Claude API 文档中，529 - overloaded_error 的意思是“API 暂时过载”，文档还指出，529 错误可能会在所有用户的高流量期间发生。

这使得 API 错误 529“过载”：重试、退避和回退策略 不同于格式错误的请求、错误的 API 密钥，或普通的配额问题。第一反应不应该是“修改提示词”或“购买更多配额”。第一反应应该是一套受控的可靠性应对方案：对故障进行分类，只在预算范围内重试，保护用户免受重试风暴影响，并判断何时回退路线比等待更安全。

本指南面向在生产环境中运行 LLM、智能体或多模态工作负载的 AI 产品和平台团队。它为你提供可直接复制到事故运行手册中的实用错误-行动矩阵、重试预算、退避模式以及回退决策流程。

快速答案

对于 API 错误 529“过载”：重试、退避和回退策略，请使用以下默认策略：

1. 将 529 overloaded_error 视为临时的服务提供商容量信号，而不是客户端验证错误。
2. 对幂等或只读请求使用带抖动的指数退避进行重试。
3. 当服务提供商发送 retry-after 时，应遵循该指示。
4. 在很小的重试预算后停止，交互式流量通常为两到三次尝试。
5. 不要盲目重试非幂等的工具调用、写入操作、购买、电子邮件或任何可能已经产生副作用的操作。
6. 当 529 错误按服务提供商、模型、端点或区域聚集出现时，打开熔断器。
7. 仅当备用模型能够满足相同的产品契约时，才进行回退。
8. 记录 request-id、模型、路由、重试次数、最终结果以及对用户可见的影响。

换句话说：短暂重试，降低整体流量，在等价可接受时切换到备用方案，并在请求不再适合重复时停止。

为什么会发生 API 错误 529 过载

529 overloaded_error 是一种容量状态。它通常意味着你的请求已经到达服务提供商，但服务提供商一侧当前过于繁忙，无法处理该请求。Anthropic 将其与 429 rate_limit_error 分开说明。这个区别很重要：

即使你自己的工作负载没有任何异常，在提供商全局流量激增期间也可能出现 529。但如果你正在推出新功能、运行批处理，或发送突然增加的代理群，也应检查你的流量爬升是否导致了本地压力或加速限制行为。

错误-操作矩阵

在恐慌性修改代码之前，先使用这个矩阵。

这正是大多数通用错误页所忽略的部分：过载模型不仅仅是一个 HTTP 状态。它还是关于重复工作、延迟、输出质量和用户信任的产品决策。

529 的安全重试策略

先为交互式和后台工作负载分别设置重试预算。

最简单的重试形式是带抖动的指数退避：

function backoffMs(attempt: number) {
  const base = 250;
  const cap = 8_000;
  const exponential = Math.min(cap, base * 2 ** attempt);
  const jitter = Math.floor(Math.random() * exponential * 0.4);
  return exponential + jitter;
}

对于交互式产品，请使用较小的值。一个重试 60 秒的聊天消息在技术上可能足够有韧性，但对用户来说仍然会感觉像坏了。对于后台队列，请使用更宽的退避窗口，并保留工作项以便稍后处理，而不是不断猛击提供商。

尊重 Retry-After，但不要依赖它

一些 API 会针对速率限制或瞬时故障发送 retry-after 标头。Anthropic 的文档说明，官方 SDK 会使用指数退避重试瞬时故障，默认重试两次，并在存在时遵循 retry-after。如果你绕过或封装了 SDK，你自己的控制器也应该这样做。

但是，不要构建一个只有在 retry-after 存在时才有效的策略。529 响应并不总是会带着有用的等待时间返回。你的回退控制器仍然需要：

• 最大尝试次数，
• 最大总耗时预算，
• 按路由的熔断器，
• 队列年龄限制，
• 以及最终面向用户的失败模式。

避免重试风暴

针对提供方过载，最糟糕的响应就是同步重试流量。如果每个工作线程都立即重试，你会把一次提供方事故变成更大的事故。

添加这些控制：

AWS 关于 retry-with-backoff 的指导也表达了同样的运维观点：重试有助于处理瞬时故障，但过多重试会增加争用并加剧服务降级。

何时应回退而不是重试

回退不等同于重试。重试是让同一路由再试一次。回退则是更改路由、提供方、模型、区域或能力。

当以下四个条件都为真时，使用回退：

1. 主路由正在因 529 或相关瞬时错误而反复失败。
2. 在增加延迟之后，用户或工作负载仍然会从响应中受益。
3. 备用路由满足相同的产品契约。
4. 该请求尚未产生部分输出或不确定的副作用。

使用如下路由契约：

task: support_reply_draft
primary:
  model: claude-sonnet-current
  max_attempts: 2
  retry_on: [529, 500, 502, 503, 504, timeout]
  backoff: exponential_jitter
fallback:
  model: approved-general-chat-model
  allowed_when:
    - no_partial_stream_output
    - no_write_side_tool_executed
    - response_schema_compatible
    - latency_budget_remaining_ms > 3000
stop:
  user_message: "The model is overloaded. Please retry in a moment."
log:
  fields:
    - request_id
    - route
    - model
    - retry_count
    - fallback_used
    - final_status

如果你的产品依赖于精确的模型行为、工具调用格式、引用策略、安全行为，或者长上下文特性，那么跨模型回退可能比明确失败更糟。对于这类工作负载，回退到同一提供方/模型的另一路由，比回退到不同模型家族更安全。

对于这一决策背后的更广泛架构，请将此错误页面与 Flatkey 的 LLM API 回退路由生产手册以及模型回退策略工作流手册配合阅读。这些指南涵盖了更大的控制器模式；本页则专注于 529 过载响应。

529 的幂等性规则

重试安全性取决于幂等性。AWS 指南指出，在使用退避重试时，操作应当是幂等的；否则，部分更新可能会破坏状态。Stripe 的底层错误指南也对网络和服务器错误给出了同样的观点：失败或不明确的请求可能会让客户端无法确定服务器是否已接收或执行了该请求。

对于 AI 产品，请将这一规则应用到工具和副作用上：

实用规则很简单：如果重复请求可能创建重复的外部状态，就不要让通用重试包装器来处理它。

熔断器阈值

熔断器会将重复过载转化为临时的路由决策。你不需要一个复杂的系统就可以开始。

可以使用如下策略：

• 当某条路由在两分钟内 529 占比超过 20%，且至少尝试了 20 个请求时，打开熔断器。
• 对于交互式流量，让熔断器保持打开 60-180 秒。
• 在关闭熔断器之前，发送少量探测请求。
• 缓慢重置；不要一次性把整个队列全部回灌到该路由。
• 在可能的情况下，按提供商、模型、端点族和区域跟踪熔断器状态。

熔断器对代理系统尤其重要，因为代理通常会在多个层级重试：模型 SDK、编排库、作业 worker 和用户命令循环。每一层都要计入，否则你可能会不小心放大重试预算。

可观测性检查清单

对于每一次 529 事件，记录足够的证据来回答四个问题：哪里失败了、为什么会重试、是否发生了回退，以及用户看到了什么。

Flatkey 团队也可以用相同的模式通过 https://router.flatkey.ai/v1：通过一个 OpenAI 兼容的基础 URL 路由，保持模型选择明确，并在事件后查看使用日志。Flatkey 的快速入门文档将共享密钥、模型目录、路由器基础 URL 和使用日志列为用来核实请求流量和成本的位置。

如果你仍在将速率限制处理与过载处理分开，请参考 LLM 速率限制指南了解 429/RPM/TPM 策略，并参考 AI 路由 API 指标指南了解可靠性报告。

Flatkey 如何适配 529 恢复计划

Flatkey 不应被视为一种假装过载不会发生的方式。上游模型提供方仍然可能繁忙。网关的有用角色是运营控制：

• 一个用于模型流量的 OpenAI 兼容基础 URL。
• 一个用于已批准回退候选项的共享模型目录。
• 一个用于重试和已恢复失败的统一使用与成本账本。
• 无需重写每个应用客户端即可更快地更改路由策略。
• 当产品、平台和财务团队审查该事件时，审计轨迹更清晰。

对于生产团队来说，这通常比更大的重试循环更有价值。更大的重试循环可能会把事件隐藏起来，直到它们变得昂贵。路由化策略可以让过载变得可见且可控。

API 错误 529 的生产运行手册

将以下内容复制到你的事件流程中：

1. 确认错误类别：529 overloaded_error、提供商、模型、端点、时间戳和请求 ID。
2. 检查请求是否为只读、流式传输，还是写入侧请求。
3. 使用指数退避和抖动，应用该路由的重试预算。
4. 如果请求产生了部分输出或存在不确定的副作用，则停止重试。
5. 如果 529 在同一提供商/模型路由上成簇出现，则开启熔断器。
6. 仅在可接受的输出、安全性、延迟和成本行为都兼容的已批准路由上回退。
7. 当延迟预算耗尽时，向用户展示可见消息。
8. 在事件结束后，回顾重试次数、回退次数、已恢复请求、失败请求以及防止重复的证据。

常见问题

API 错误 529 和 429 是一回事吗？

不是。在 Anthropic 的文档中，529 表示 API 暂时过载，而 429 是速率限制错误。应将 529 视为提供商过载，将 429 视为速率/配额/流量形态问题，直到你的日志证明并非如此。

我应该重试 API 错误 529 吗？

是的，但只能在预算范围内，并且仅当该请求可以安全重复时。使用带抖动的指数退避，若存在则遵循 retry-after，并在部分输出或外部副作用使重放不安全时停止。

对于 529 过载错误，我应该重试多少次？

对于交互式 AI 功能，先从两次重试和严格的墙钟截止时间开始。后台任务可以使用更多重试，但应使用队列时长限制、死信处理和熔断器。

在 529 之后我应该自动切换模型吗？

只有当回退模型能够满足相同的产品契约时才可以。如果模型特定行为、工具、模式、安全策略或上下文长度很重要，那么回退可能需要一个用户可见的“用另一个模型重新生成”操作，而不是透明切换。

在 529 事件期间我应该向用户显示什么？

使用清晰的临时状态语言：“模型已过载。我们正在短暂重试。”如果重试预算耗尽，提供一个重试按钮或降级替代方案。除非你的用户是需要这些细节的开发者，否则不要暴露提供商内部信息。

最终建议

最安全的 API 错误 529“过载”：重试、退避和回退策略 方案不是一个单独的 while retry 循环，而是一种路由策略：短暂重试瞬时过载、使用抖动退避、保护非幂等工作、对重复失败进行熔断，并且只有在替代路由能够保留用户契约时才进行回退。

如果你的团队已经运行多个模型或提供商，请将该策略置于一个网关之后。使用 Flatkey，你可以将兼容 OpenAI 的客户端指向 https://router.flatkey.ai/v1，把回退候选项保存在一个模型目录中，并在上线后通过 Usage Logs 查看已恢复的失败。

如果你需要第一调用路径，请从 Flatkey API 快速入门 开始；或者在 Claude API 代理与多模型路由器对比 中比较工作负载级路由选项。

已检查的来源

• Anthropic Claude API errors: https://platform.claude.com/docs/en/api/errors
• AWS Prescriptive Guidance, retry with backoff pattern: https://docs.aws.amazon.com/prescriptive-guidance/latest/cloud-design-patterns/retry-backoff.html
• Stripe advanced error handling and idempotency: https://docs.stripe.com/error-low-level
• Flatkey documentation index: https://docs.flatkey.ai/index.md
• Flatkey quickstart: https://docs.flatkey.ai/quickstart.md
• Flatkey product overview: /Users/solveainc/.11agents/flatkey/knowledge_base/information/what-we-do/product-overview.md
• Flatkey marketing strategy: /Users/solveainc/.11agents/flatkey/knowledge_base/marketing/strategy.md