Claude Code 的 "529 Overloaded" 错误：它是什么，真正有效的解法是什么

一次 Claude Code 会话进行到一半，"API Error: 529 Overloaded" 突然出现，大多数人的第一反应是再敲一次回车。这没有用，而且用完的并不是你的额度：是 Anthropic 的 API 暂时过载，官方文档写得清清楚楚。更重要的是，当你盯着屏幕时，CLI 其实已经在自动重试了。真正的损失在别处，在你并行启动的那些智能体身上。

"529 Overloaded" 是什么意思？

意思是 Anthropic 的 API 暂时过载。这不是你的代码、你的密钥或者你的套餐出了问题。

在 Claude API 官方错误文档中，状态码 529 对应的类型是 overloaded_error，定义只有一句："The API is temporarily overloaded"。紧接着的提示才是解开疑惑的关键："529 errors can occur when the API experiences high traffic across all users"。是所有用户的高流量，不是你一个人的。

返回的内容长这样：

{
  "type": "error",
  "error": {
    "type": "overloaded_error",
    "message": "Overloaded"
  },
  "request_id": "req_011CeME4MStM56TRJaC3dWRJ"
}

请保留 request_id。每个 API 响应里都有它，响应头 request-id 中也有，这是 Anthropic 支持团队追踪具体某次请求时要的东西。

是我的额度，还是 Anthropic 的问题？

是 Anthropic 的问题。代表“你的额度”的是另一个状态码：429。把两者搞混，你就会去修一个本来不属于你的问题，白白换模型或者换套餐。

状态码	类型	是谁的问题	该做什么
429	rate_limit_error	你的。组织触发了速率限制或支出上限	等窗口过去，检查限额或套餐
529	overloaded_error	Anthropic 的。所有用户的流量高峰	让自动重试自己跑完
500	api_error	Anthropic 的。意外的内部错误	用指数退避重试；持续出现就带着 request_id 联系支持
504	timeout_error	请求耗时太长	改用流式 Messages API

想确认是普遍现象还是只有你遇到，在动配置之前先看 status.claude.com。

我需要一直手动重试吗？

不需要。CLI 本来就会自己重试，而且会在屏幕上显示已经试了几次。

你看到的那行字，记录在官方仓库的 issue #91817 里，就是这样：

✻ 529 Overloaded · Retrying in 4s · attempt 6/10

最多 10 次，每次之间的等待时间递增。中途关掉终端再打开，等于把已经完成的尝试全部丢掉、从零重新计数，这和你想要的正好相反。

如果你不用 CLI，而是通过 SDK 直接调 API，默认值更保守。官方 SDK 对瞬时故障默认用指数退避重试两次，在存在 retry-after 响应头时会遵守它。可以在客户端把这个次数调高：

client = anthropic.Anthropic(max_retries=5)

为什么我并行启动的智能体会一起失败？

因为它们是一起出发的。当编排器一次性扇出多个智能体时，所有的第一个请求会在同一瞬间打到 API 上，一次短暂的过载就会带走整批，而不只是其中一两个。

issue #90043 描述了这个模式，标题本身就是诊断结论："Fan-out launches agents without stagger, causing correlated 529 failures"。启动之间没有抖动，失败就会彼此相关。

Anthropic 自己的文档在讲加速限制时给出的建议正好相反："ramp up your traffic gradually and maintain consistent usage patterns"。逐步爬升，而不是制造尖峰。实际做法很简单，把启动时间摊开就行：

import random, time

for task in tasks:
    launch(task)
    time.sleep(random.uniform(0.5, 2.0))

两秒的启动延迟，比整批重做便宜得多。

子智能体挂掉时，怎么才能不丢掉已完成的工作？

这是 529 隐藏的代价，也是最贵的一项。后台子智能体因为这个错误挂掉时，不会返回任何部分结果：任务直接算失败，唯一的出路是从零重启。issue #89267 描述的正是这一点，第二次运行会把第一次已经做完的工作重做一遍，并且再付一次钱。

在这个行为改变之前，防守手段是架构层面的：把长任务拆成若干步骤，每一步完成就把结果写到磁盘，而不是一个一小时的任务只在最后交付。这样一次 30 秒的过载损失的是一个步骤，而不是整个任务。

无人值守的自动化任务同样要小心：定时任务因 529 失败后，仍可能被算作已完成的运行并发出成功通知，这个行为记录在 issue #92423 中。如果你的 cron 只信任退出码，请再确认一下是否真的产出了东西。

如果 529 每天都出现呢？

那它就不再是一次事故，而是一种依赖。上面所有的办法依然有效，但没有一个能改变这个事实：队列由另一家公司控制。