目录
在 Claude Code 里工作时，你是否曾因为突然弹出这样的错误而被打断？
API Error: 529 {"type":"error","error":
{"type":"overloaded_error","message":"Overloaded"}}
# 或者
API Error: 500 Internal server error.529 Overloaded 的意思是「Anthropic 一侧的 API 临时过载（拥挤）」，500 则是「服务器内部发生了预料之外的错误」。两者都是服务器端的问题——而最关键的一点是——这既不是你的请求或设置有错，也不是用量额度用尽了。官方文档也明确写道：「529 不是你的用量上限，也不会计入你的配额。」换句话说，这类错误基本上「稍等片刻再重试」就能解决。
先说要点。（1）529/500 属于服务器端——不是你的错（也不消耗配额）。（2）Claude Code 在向你显示任何提示之前，已经以指数退避自动重试最多 10 次——当那条友好提示出现时，这些重试其实已经用尽。（3）应对方式是「查看状态页 → 稍等 → 用 /model 切换模型」。容量是按模型分别管理的，所以即使 Opus 很忙，Sonnet 往往也能通过。
这是服务器端问题，不是你的错
— Claude Code 在向你显示任何提示之前就已经在重试
所以应对方式就是 「等待并重试 / 用 /model 切换 / 查看 status.claude.com」。
基本上没有需要修改的代码或设置。
1. 这个错误到底在说什么
HTTP 529（overloaded_error / 消息为 "Overloaded"）是Anthropic 的 API 临时超出容量、陷入拥挤的信号。官方的描述原文就是「API 临时过载」「当 API 在所有用户范围内经历高流量时可能发生」。也就是说，这并非某个特定的人的错，而是整体需求一时超过了供给的状态。
HTTP 500（api_error）是Anthropic 一侧内部发生了预料之外的错误。文档称它「并非由你的提示词、设置或账户引起」。与之相关的还有504（timeout_error），即长时间请求超时（请注意，Anthropic 官方定义的是 504，而 502/503 通常来自网关等上游基础设施）。
最关键的一点是：「529、500 是服务器端的问题，不会消耗你的用量配额。」它们与用尽套餐额度的 usage limit reached、以及你自己的速率限制 429 完全不是一回事（§4 会做区分）。所以无需紧张地去修改代码或设置——默认做法就是「等待并重试」。
2. Claude Code 已经在自动重试
事实上，在你看到错误消息之前，Claude Code 早已在后台多次重试。根据官方文档——
自动重试的机制
服务器错误、过载（overloaded）响应、请求超时、临时的 429 限流以及连接中断，都会以指数退避自动重试最多 10 次。重试期间，加载指示器会显示 Retrying in Ns · attempt x/y 的倒计时。等到那条友好的 API Error: 字样出现时，那 10 次重试已经用尽。
所以「529 闪了一下但马上继续运行」是正常现象——是自动重试吸收了它。反过来，如果你看到了那条友好提示（「Repeated 529 Overloaded errors … try again in a moment. If it persists, check https://status.claude.com」等），那就是负载严重到连重试都无法恢复的信号。你可以用 CLAUDE_CODE_MAX_RETRIES（默认 10）调整重试次数，用 API_TIMEOUT_MS（默认 600000 ms＝10 分钟）调整单次请求的上限——在脚本场景中想要快速失败就调低次数，想要熬过较长的故障事件就调高。
3. 用户端的应对
面对 529/500，可采取的招数其实非常简单。按顺序逐一尝试。
基本就是「等待、切换、确认」
/feedback 反馈（附上 request_id 能加快排查）。
拿不准？1）等待 → 2）用 /model 切换 → 3）查看 status。
错峰到非高峰时段也有帮助。基本上没有需要修改的设置。
补充：「Server is temporarily limiting requests（正在临时限制请求）」这条消息，官方也将其定位为「与你的用量上限无关的短时服务器端限流」。它同样稍等片刻就会恢复，与套餐额度的 usage limit 是两回事。
4. 与相似错误的区分
「卡住了」这一类错误，原因可能截然相反。先按「是服务器端还是你这边？」做大致划分。
| 错误 | 谁的问题 | 消耗配额？ | 主要应对 |
|---|---|---|---|
| 529 Overloaded | 服务器端（容量问题，所有用户共通） | 不消耗 | 等待并重试、/model、查看 status |
| 500 / 504 | 服务器端（内部错误／超时） | 不消耗 | 重试；若持续则 /feedback |
| 429 Rate limit | 你这边（你的 API 密钥速率上限） | 消耗（你的速率额度） | 降低流量、提升 tier、按 retry-after 等待 |
| usage limit reached | 你这边（Pro/Max 套餐额度） | 消耗（套餐额度） | 等待重置；应对方法 |
| 400 Invalid request | 你这边（请求有误） | 不消耗 | 修正请求内容 |
记忆口诀：5xx（含 529）属于服务器端＝等一等就好。 429 和 usage limit 关乎你的「量」＝需要调整速率或套餐。 400 关乎你的「内容」＝修正请求。 尤其是 429 和 529 特别容易混淆，但 429 会带 retry-after 响应头并消耗配额，而 529 既没有响应头也不消耗配额——是两回事。Claude Code 其他常见错误，请参见错误集锦。
5. 面向开发者（API/SDK）
如果你在用 API/SDK 运行自建应用，正确的设计是把 529/500 当作「正常情况下可能发生的一过性事件」纳入考量。
（1）官方 SDK 会抛出带类型的异常（OverloadedError、InternalServerError 等），并以指数退避对临时错误自动重试——请用异常类来捕获，而不是字符串匹配。 （2）如果你自己重试，请采用「指数退避 ＋ 抖动（jitter）」。 （3）retry-after 响应头在 429 上存在，但在 529 上不存在，因此遇到 529 时要用你自己的退避来等待，而非依赖响应头的时序。（4）准备一个后备模型（Claude Code 有 --fallback-model）。（5）逐步爬升流量，以避免用量激增后触发 429 的「加速度限制」。如果你需要稳定的可用性，Priority Tier 和 Message Batches API 也是可选项。基础知识请参见 什么是 AI API。
6. 是一时尖峰，还是故障事件？
同样是 529/500，究竟是「转瞬即逝的尖峰」还是「反复出现的持续故障」，含义大不相同。
一时的尖峰（一次或几次、重试即可通过）属于需求波动的正常范围。自动重试通常会吸收掉它，你这边没有什么需要修复的。另一方面，「Repeated 529」，或者重试也消不掉的 500，则是该怀疑有正在进行的故障事件的信号——首先查看 status.claude.com，如果有故障公告，等待恢复是唯一正确的做法。如果没有故障公告但 500 持续，请通过 /feedback 附上 request_id 反馈。无论哪种情况，用户对 529/500 能做的只有「重试、用 /model 切换、查看状态、反馈」——而这其实也就够了。
总结
Claude Code 的 「API Error: 529 Overloaded」和「500 Internal server error」，都是Anthropic 一侧的 API 临时过载、或遇到内部错误的服务器端事件。它们既不是你的请求或设置有错，也不是用量额度用尽，更不消耗配额。Claude Code 在向你显示任何提示之前会以指数退避自动重试最多 10 次；那条友好提示出现，就意味着这些重试已经用尽。
应对很简单：（1）等待并重试 → （2）用 /model 切换模型（容量按模型分别管理）→ （3）查看 status.claude.com → （4）500 持续就用 /feedback。它们与 429（你的速率）和 usage limit（你的套餐）是两回事，且 529 不带 retry-after。开发者应通过 SDK 的自动重试、指数退避 ＋ 抖动，以及后备模型来加以设计应对。如果反复出现，就怀疑是故障事件并查看状态页——无论哪种情况，基本上都没有需要修改的代码或设置。相关阅读：usage limit 应对方法、Opus/Sonnet/Haiku 对比、Claude Code 错误集锦。
FAQ
Q. 「529 Overloaded」是我用法不对、或者我的代码有问题吗？
A. 不是——这是服务器端的问题。529 意味着 Anthropic 的 API 临时过载（所有用户范围内的拥挤），与你的请求、设置、账户都无关。官方也明确指出「529 不是你的用量上限，也不会计入你的配额。」通常只要稍等片刻再重试就能解决。
Q. 它老让我重试——我该自己拼命狂点吗？
A. 一般不需要。Claude Code 在显示错误之前已经以指数退避自动重试最多 10 次（Retrying in Ns · attempt x/y）。那条友好提示之所以出现，是因为那 10 次重试已经用尽。稍等一会儿，对于很长的提示词只需输入「再来一次」，就能在保留原有上下文的情况下重新运行。次数可用 CLAUDE_CODE_MAX_RETRIES 调整。
Q. 529 和 429 有什么区别？
A. 529 是服务器端的过载（所有用户共通；不消耗你的任何配额），而 429 是你自己的速率限制（你超出了 API 密钥的 RPM 等——是你的速率额度问题）。一个辨别窍门：429 会带 retry-after 响应头，而 529 则不会。429 需要你这边来调整（降低流量、提升 tier）；529 只需等待并重试或用 /model 切换。
Q. 为什么用 /model 切换有时就能通过？
A. 因为容量（拥挤程度）是按模型分别管理的。即使 Opus 处于高负载，只要 Sonnet 还有余量就可能立刻通过。Claude Code 自身在高负载时有时也会提示切换（「Opus is experiencing high load, please use /model to switch to Sonnet」）。赶时间时，用 /model 切换到更轻量或别的模型，是一种快捷的规避手段。
Q. 我一直不停地遇到 529/500。该怎么办？
A. 怀疑有正在进行的故障事件，并查看 status.claude.com。如果有故障公告，你能做的就只有等待恢复。如果没有故障公告但 500 持续，请通过 /feedback 附上 request_id 反馈，以便 Anthropic 排查。由于 529/500 都是服务器端事件，基本上没有需要你去修改的代码或设置。
