排错

Claude Code 报 529 Overloaded 是什么意思，怎么办

Q: Claude Code 报 529 Overloaded 是什么意思？

说明 Anthropic 的 API 暂时过载。Anthropic 的 API errors 页面把 529 定义为 overloaded_error：“The API is temporarily overloaded.”全体用户流量很高时可能出现，所以不是你的配置造成的。

Q: Claude Code 的 API Error 529 是我的用量限制吗？

不是。Claude Code 的错误参考写明，529 不是你的用量限制，也不计入额度。速率限制对应的是 429 rate_limit_error，是另一种错误。

Q: Claude Code 里 529 和 429 有什么区别？

429 rate_limit_error 是你的组织触到了速率限制或支出上限；529 overloaded_error 是 API 在全体用户范围内达到容量上限。429 要减少自己的请求；529 就等一等、看状态页，或者用 /model 换模型。

Q: 报 overloaded 时可以换模型吗？

可以。运行 /model 选另一个模型。Claude Code 的错误参考说容量是按模型统计的，所以一个模型负载高时，换一个模型可以继续工作。

发布于 2026 年 11 月 5 日 · 最后核对 2026 年 11 月 5 日

Claude Code 显示 API Error: 529 Overloaded 或 overloaded_error，说明 Anthropic 的 API 暂时过载。这不是你的用量限制，也不是你的配置有问题。本文讲 529 的含义、它和 429、500 的区别、Claude Code 已经替你重试了什么，以及你能做什么。内容依据 Anthropic 的 API errors 页面和 Claude Code 的 Error reference，核对于 2026 年 11 月 5 日。

要点

Anthropic 的 API errors 页面把 529 定义为 overloaded_error：“The API is temporarily overloaded.”（API 暂时过载）。
全体用户的流量很高时可能出现 529。Claude Code 文档写明，它不是你的用量限制，也不计入你的额度。
Claude Code 会自动重试，默认最多 10 次，之后才显示这个错误。
可以做的：看 status.claude.com，等几分钟再试，或者用 /model 换一个模型，因为容量是按模型统计的。

529 Overloaded 是什么意思

Anthropic 的 API errors 页面把状态码和错误类型放在一起列出。这个错误对应的一行是：

529 - overloaded_error: The API is temporarily overloaded.

同一页还有一条警告：“A 529 error can occur when the API experiences high traffic across all users.”也就是说，全体用户流量很高时就可能出现 529。Claude Code 的错误参考说法一致：API 在所有用户范围内暂时达到容量上限，Claude Code 在显示这条消息之前已经重试了好几次。文档还明确写了：“A 529 is not your usage limit and doesn't count against your quota.”（529 不是你的用量限制，也不计入额度。）

终端里看到的消息类似下面这样，出自 Claude Code 的错误参考：

API Error: Repeated 529 Overloaded errors. The API is at capacity — this is usually temporary. Try again in a moment. If it persists, check https://status.claude.com.

最后一句会因提供方不同而变化。某个模型负载特别高时，Claude Code 也可能显示 Opus is experiencing high load, please use /model to switch to Sonnet。

529、429、500 的区别

它们是不同的错误，原因也不同。下面的定义来自 Anthropic 的 API errors 页面。

状态码	类型	含义（原文大意）
429	`rate_limit_error`	你的组织触到了速率限制、达到所在用量档位的月度支出上限，或达到 Claude Code 工作区的支出上限。
500	`api_error`	Anthropic 系统内部出现意外错误。用指数退避重试；持续出现就带上 request ID 联系支持。
529	`overloaded_error`	API 暂时过载。

实际区别：429 说的是你自己的限额，减少请求或提高限额有用；529 说的是 API 在全体用户范围内的容量，和你的账号无关。API errors 页面提到一种交叠：组织用量突然大幅上升时，少数情况下会因为 API 的加速限制（acceleration limits）出现 429，建议逐步增加流量并保持用量稳定。

API errors 页面没有列出 503 这一行。Claude Code 的错误参考说，任何 5xx 响应它都会显示状态码和 API 的错误消息，所以 529 以外的 5xx 会带着自己的状态码和消息出现。

Claude Code 已经替你重试了什么

Claude Code 遇到暂时性故障，会用指数退避最多重试 10 次，之后才把错误显示给你，过载响应就在重试范围内。重试时，加载提示会显示 Retrying in Ns · attempt x/y 倒计时。所以你最终看到 529 消息时，该做的重试已经做过了。

遇到 529 时重试可能提前结束。Anthropic 的环境变量页面举了个例子：用 API 密钥且模型是 Opus 时，第三次 529 就会停止，并显示 Repeated 529 消息。如果设置了 fallbackModel，Claude Code 会改用那个模型，而不是显示错误。设置参考把 fallbackModel 描述为：主模型过载或不可用时，按顺序尝试的备用模型。

和重试有关的环境变量

下面的名称和默认值来自 Claude Code 的错误参考。重试变量对整个会话生效，按需使用。

变量	默认值	作用
`CLAUDE_CODE_MAX_RETRIES`	10	重试次数。在脚本里调低它可以更快暴露失败。
`CLAUDE_CODE_RETRY_WATCHDOG`	未设置	在 CI 等无人值守的会话里设为 `1`，429 和 529 容量错误会无限重试，而不是在 `CLAUDE_CODE_MAX_RETRIES` 次后失败。
`CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS`	500	529 重试之间退避的起始延迟（毫秒），最高可调到 32000。需要 Claude Code v2.1.292 或更高。
`CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS`	32000	该退避的延迟上限（毫秒），最高可调到 64000。需要 Claude Code v2.1.296 或更高。
`API_TIMEOUT_MS`	600000	每次请求尝试等待响应头的时间（毫秒）。不限制之后流式响应持续多久。

例如，让无人值守的任务在容量问题期间等待而不是失败：

export CLAUDE_CODE_RETRY_WATCHDOG=1

$env:CLAUDE_CODE_RETRY_WATCHDOG = "1"

按同一份参考，设置了 watchdog 之后，上面两个过载延迟变量不再起作用。

看 Anthropic 的状态页

Claude Code 的错误参考建议到 status.claude.com 查看容量公告。重试过程中，在 Anthropic API 上遇到 529，提示行也会指向 status.claude.com。如果你通过中转使用 Claude Code，中转自己有状态页；CoreCode 的在 /status/。

你能做什么

等几分钟再重发。Claude Code 的参考就是这样建议的。
看状态页有没有容量公告。
用 /model 换模型。容量按模型统计，一个模型负载高时，换一个可能还能用。检测到某个模型负载高时，Claude Code 也会提示你这样做。
设置备用模型。用 fallbackModel 设置后，主模型过载时 Claude Code 会自动切到备用模型。
逐步提高流量。API errors 页面建议逐步增加流量并保持用量稳定，这针对的是 429 加速限制的情况。

如果你在自己的代码里调用 API，Anthropic 官方 SDK 会自动重试暂时性故障（包括 5xx），用指数退避，默认两次。重试次数可以用 SDK 客户端的 max_retries 配置。

通过 CoreCode 使用 Claude Code 时

CoreCode 是由官方 Claude 账号应答的中转。Claude Code 用 ANTHROPIC_BASE_URL=https://corecode.live 指向它，密钥放在 ANTHROPIC_AUTH_TOKEN，设置方法见 Claude Code 接入指南。CoreCode 的报错排查页对 529 的说法是：Anthropic 官方暂时过载，和你的配置无关，Claude Code 会自动重试；持续几分钟以上时先看服务状态，也可以临时用 /model 换一个模型。

其他状态码，同一页还写了 429（单个密钥的请求速率或并发超限）和 5xx，包括 CoreCode 发布期间返回的 503，它带有 Retry-After: 5。

常见问题

Claude Code 报 529 Overloaded 是什么意思？

说明 Anthropic 的 API 暂时过载。Anthropic 的 API errors 页面把 529 定义为 overloaded_error：“The API is temporarily overloaded.”全体用户流量很高时可能出现，所以不是你的配置造成的。

Claude Code 的 API Error 529 是我的用量限制吗？

不是。Claude Code 的错误参考写明，529 不是你的用量限制，也不计入额度。速率限制对应的是 429 rate_limit_error，是另一种错误。

Claude Code 会自动重试 529 吗？

会。Claude Code 对暂时性故障用指数退避最多重试 10 次，之后才显示错误，过载响应在重试范围内。次数可以用 CLAUDE_CODE_MAX_RETRIES 调整；无人值守、需要一直重试 429 和 529 的会话可以设置 CLAUDE_CODE_RETRY_WATCHDOG=1。

怎么看 Claude Code 今天是不是过载了？

打开 status.claude.com，Claude Code 的错误参考就是让你在那里看容量公告。如果你用 CoreCode，它自己的状态在 /status/。

Claude Code 里 529 和 429 有什么区别？

429 rate_limit_error 是你的组织触到了速率限制或支出上限；529 overloaded_error 是 API 在全体用户范围内达到容量上限。429 要减少自己的请求；529 就等一等、看状态页，或者用 /model 换模型。

报 overloaded 时可以换模型吗？

可以。运行 /model 选另一个模型。Claude Code 的错误参考说容量是按模型统计的，所以一个模型负载高时，换一个模型可以继续工作。

来源

Claude API: Errors（529 overloaded_error 一行、高流量警告、429 与 500 的定义、SDK 重试；核对于 2026 年 11 月 5 日）
Claude Code: Error reference（Repeated 529 Overloaded errors、自动重试、调整重试行为；核对于 2026 年 11 月 5 日）
Claude Code: Environment variables（CLAUDE_CODE_MAX_RETRIES 以及 watchdog 和过载延迟变量；核对于 2026 年 11 月 5 日）
Claude Code: Settings reference（fallbackModel；核对于 2026 年 11 月 5 日）
Claude status（Anthropic 的状态页；核对于 2026 年 11 月 5 日）