Claude Code 一直报 529 Overloaded 怎么办？先分清是服务端还是你这边
干着干着，屏幕上开始刷这么一串：
API Error (529 {"type":"error","error":{"type":"overloaded_error","message":"Overloaded"}})
· Retrying in 1 seconds… (attempt 1/10)
API Error (529 ...) · Retrying in 1 seconds… (attempt 2/10)
API Error (529 ...) · Retrying in 2 seconds… (attempt 3/10)
attempt X/10 一路数上去，数完还是失败。这是 Claude Code 里最让人干着急的一类报错——你什么都没做错，但也什么都做不了。
这篇讲三件事：这套重试机制到底在干什么、官方给的处理是什么、以及怎么判断这次是不是真的轮不到你。
一、先看懂 attempt X/10
那个 /10 不是随便写的。官方文档说明：Claude Code 在把错误摆到你面前之前，会自动重试瞬时故障，最多 10 次。
也就是说，你看到的那一屏刷屏，是它在替你扛。扛到第 10 次还不行，才报到你眼前。
这个次数是可以调的，官方给了三个相关的环境变量：
| 环境变量 | 默认值 | 说明 |
|---|---|---|
CLAUDE_CODE_MAX_RETRIES | 10 | 最大重试次数，最高可设到 15 |
CLAUDE_CODE_RETRY_WATCHDOG | — | 无人值守会话建议设为 1 |
API_TIMEOUT_MS | 600000（10 分钟） | 单次请求的超时时间 |
CLAUDE_CODE_MAX_RETRIES 最高只能到 15，这个上限值得记住——它意味着调这个参数的收益是有限的。从 10 调到 15，多扛五次，如果服务端的拥塞持续几分钟，多这五次也救不了。
CLAUDE_CODE_RETRY_WATCHDOG 那条对跑无人值守任务的人更实用。官方的建议是在这种会话里设为 1——你人不在跟前，多一层看护是有意义的。
二、官方给的处理
针对 Repeated 529 Overloaded errors，官方错误参考页给的处理是三条：
- 查 status.claude.com 或相应提供商的状态页
- 几分钟后重试
- 运行
/model切换到不同模型
第三条是三条里唯一能立刻起作用的。529 的成因是「API 容量不足」，而不同模型的容量压力不一定同时紧张——换一个模型试试，是成本最低的一次尝试。
第一条要说明一下它的局限。GitHub 上 issue #3572（已关闭，273 条评论）里，很多人反映的正是「状态页上什么都没显示，但我这边一直 529」。状态页反映的是被官方判定为事故的情况，短时的容量紧张不一定会体现在上面。 所以状态页干净，不等于你这边没问题——它只能作为一个正向信号（如果上面确实报了故障，那你就不用查自己了）。
一句必要的话：issue #3572 的评论区里有不少关于「算力被挪去做别的」之类的说法。那些都是用户猜测，没有任何官方来源。本文不引用，也建议你排查时不要往那个方向想——它既不能帮你解决问题，也没法验证。
三、怎么判断这次是不是服务端的问题
比起干等，更有用的是快速判断。三个动作：
第一，换模型试一次。 /model 切到另一个模型，立刻重发。如果换了就通，基本可以确定是刚才那个模型的容量问题，跟你的网络、凭证、配置都无关。
第二，确认不是别的错误伪装的。 529 的报错体里写着 "type":"overloaded_error"，这是明确的服务端过载标识。如果你看到的其实是 429、500 或者连接类的报错，那治法完全不同——429 是限流（要查凭证和并发），500 是内部错误（等一分钟重发），连接类要查网络和代理。先看报错体里的 type 字段，别只看数字。
第三，看时间分布。 连续几分钟一直 529，和一天里偶尔跳几次，是两种情况。后者属于正常波动，自动重试就消化掉了，你甚至不会注意到。真正需要处理的是前者。
四、连续撞上 529 时的实际做法
如果确认是服务端容量问题，能做的其实不多，但有主次：
优先做的：
/model换模型——最快，成本最低- 把手上的活切成小块。大任务在半途撞上 529 会很难受，因为你不知道它做到哪了。切小之后，每一块失败的代价都小
可以做但收益有限的：
- 调高
CLAUDE_CODE_MAX_RETRIES（上限 15，只多扛五次） - 调高
API_TIMEOUT_MS（默认 600000 毫秒），这个对超时类更有用，对 529 帮助不大
不该做的：
- 不要写脚本疯狂重试。它已经在替你重试了，你在外面再套一层，只是让请求打得更密，对拥塞没有帮助
- 不要因为一次 529 就去改凭证、换网络、重装——这几样跟 529 都没关系，改了只会让你之后更难判断问题在哪
五、跟 529 长得像但不是一回事的几条
Claude Code 里有好几条报错都表现为「用不了」，别治错：
| 报错 | 官方给的处理 | 关键区别 |
|---|---|---|
529 Overloaded | 查状态页、等几分钟、/model 换模型 | 服务端容量，跟你无关 |
API Error: 500 Internal server error | 查状态页、等一分钟重发、/feedback 报告 | 服务端内部故障，官方建议主动报告 |
Server is temporarily limiting requests | 等待后重试；持续就查状态页 | 短期限流，与你的套餐配额无关 |
Request rejected (429) | /status 确认凭证、查提供商控制台限额、降低并发 | 限流，跟你的凭证和并发有关 |
You've hit your session limit / weekly limit | 等重置时间、/model 换模型、/usage 看限额 | 是你的配额用完了，跟服务端容量无关 |
这张表里最容易混的是第三条和第四条。Server is temporarily limiting requests 官方明确写了「与计划配额无关」，而 Request rejected (429) 官方给的处理里包含了降低并发——通过 CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY 这个环境变量。
如果你是在跑多工具并发的任务时频繁撞 429，这个变量才是该调的那个。 而 529 不是并发引起的，调它没用。
六、无人值守场景要多做一件事
如果你在跑自动化、CI 或者长时间无人看管的任务，529 的杀伤力比交互式使用大得多——你人不在，重试用尽之后任务就停在那了，可能几个小时后才发现。
针对这种场景：
- 设
CLAUDE_CODE_RETRY_WATCHDOG=1，这是官方对无人值守会话的建议 - 非交互模式（
-p）下，用--output-format json或stream-json，这样出错时你能从结构化输出里拿到结果字段，而不是只有一屏文字 - 任务切小。一个跑八小时的任务中途挂掉，损失的是八小时；八个一小时的任务挂掉一个，损失一小时
七、什么时候该报给官方，报什么
官方在几条服务端类报错的处理里都提到了 /feedback，但不是每条都提。值得注意这个差别：
API Error: 500 Internal server error：官方处理里明确包含/feedback报告529 Overloaded：官方处理里没有/feedback，只有查状态页、等、换模型
这个差别是有道理的。500 是「不该发生的内部故障」，报告有助于定位；529 是「容量不够」，官方那边看得到，你报了也是同样的信息。
所以：500 值得报，529 不必。 与其花时间写反馈，不如换个模型接着干。
如果你确实要报，有一条安全提醒需要知道。官方在排查页里讲 /heapdump 时写了明确警告：那个 .heapsnapshot 文件包含进程内的全部字符串，包括你的完整对话和凭证，不要附到公开 issue 上。要报的话只附 -diagnostics.json，它只有统计数据，不含对话内容和凭证。
这条虽然是讲内存问题的，但原则通用：往公开渠道贴任何诊断文件之前，先想清楚里面有没有你的代码和密钥。
八、总结
attempt X/10是它在替你重试，默认 10 次，最高能调到 15。- 官方给的三条处理里，
/model换模型是唯一能立刻见效的。 - 状态页干净不代表没问题——它只在报了故障时有正向价值。
- 先看报错体里的
type字段，别把 429、500、限流和配额用尽跟 529 混为一谈，这四类的治法完全不同。 - 不要在外面再套一层重试，也不要因此去动凭证和网络配置。
本文所引官方内容来自 Claude Code 官方错误参考文档，issue 编号来自 anthropics/claude-code 仓库，核对日 2026-08-08。产品行为会随版本变化，具体以官方文档与你所用版本为准。