如果 Claude Code 提示 API Error: 529，先把它理解成过载，而不是先理解成“我的个人额度没了”。Anthropic 的官方 API 文档把 529 定义为 overloaded_error，所以第一步不是去改套餐、换 key，或者先研究计费，而是先判断你现在面对的是实时事故、状态页已绿但同一路径还在报 529、其实看错成 429，还是 Claude Code 实际走了你没意识到的请求路径。
先看 Claude Status，然后再结合 /status 和你当前的环境变量，确认 Claude Code 实际在用哪条路径发请求。如果状态页是绿的，下一步也不是一通乱改，而是对同一路径做一次有边界的短重试，或者先做路径核对。只有这样，你才能知道报错是自己恢复了，还是还需要升级处理。
如果状态和路径都核过了，同一路径还是继续返回 529，就别再把它当成“本地再调一调就能好”的问题。把精确错误文本和任何 request_id 留下来，再升级支持。Anthropic 的错误文档、Claude Code 帮助页和状态页都在 2026-04-11 复核过；当时公开状态页是绿色。这个日期只用来提醒你: 绿色状态页并不等于 529 这条路已经自动排除。
30 秒分流板
API Error: 529 更像一个分流问题，而不是一个适合空泛讨论的概念题。你要问的不是“Claude Code 一般为什么会出错”，而是“我现在落在哪条分支上，最小正确动作是什么”。第一步先纠偏错误码: 如果日志里实际是 429 或更明确的 usage 提示，就别继续走这篇的过载脚本；如果它确实是 529，再继续走下面的过载恢复路线。
| 你现在看到什么 | 最可能归谁管 | 最安全的第一步 | 如何在同一路径验证 | 什么时候该升级 |
|---|---|---|---|---|
实际报的是 429 或 usage 提示，不是 529 | 限流或用量分支，不是真正的过载恢复 | 立刻切到限流 / 用量排查，不要继续照着 529 走 | 确认精确错误码，以及真实问题是不是套餐或 API 用量 | 澄清后发现实际仍是 529 |
| Claude Status 正在报红，或刚有新事故 | Anthropic 侧过载或服务波动 | 先停下本地改动，等状态恢复 | 事故结束后，重试之前那条同样失败的路径 | 状态恢复为绿后，同一路径仍然报 529 |
| 状态页是绿的，但同一路径还在报 529 | 短时或局部过载 | 做一次有边界的短退避重试，不要同时改一堆变量 | 确认完全相同的路径会不会自己恢复 | 多次同路径短重试后仍失败 |
| Claude Code 可能实际走了 API key、代理或别的 provider 路径 | ANTHROPIC_API_KEY 覆盖、代理路径或 auth owner 判断错误 | 先看 /status、环境变量和路由配置 | 在你原本打算测试的路径上复跑同一个请求 | 切回目标路径后仍带着当前证据报 529 |
这张表就是整篇文章最重要的部分。后面的章节只是把每一行的判断讲得更稳一点，避免你在错误分支上越修越远。最常见的时间浪费，不是“不知道怎么修”，而是先入错分支，然后做了许多看起来积极、实际上不增信号的动作。
529 到底是什么意思，为什么它不是 429
Anthropic 的 API error 文档 把这个问题说得很清楚: 429 是 rate_limit_error，529 是 overloaded_error。对用户来说，两者都可能表现成“Claude Code 不让我继续工作了”；但从恢复动作看，它们并不是一个分支。
如果错误码真的是 529，你应该先按服务过载来处理。也就是说，先看状态、做一次有边界的同路径重试、再核对请求路径，而不是先研究个人额度、费用或套餐切换。如果错误码其实是 429，那你真正要去看的就是限流和用量问题，这时更适合跳去Claude Code token 使用与限流指南或更窄的Claude Code rate limit reached 修复指南。
很多人之所以把两者混在一起，是因为他们只记得“被拦住了”，却没有保留精确错误码。但对排障来说，错误码本身就是路线图。529 不会自动等于“我的计划额度见底了”，429 也不会因为服务看起来忙就变成过载分支。
所以最实用的习惯是: 在你做任何昂贵或破坏性动作前，先确认精确错误码。如果它写的是 529 或 overloaded_error，继续看这篇；如果它写的是 429 或更清楚的配额警告，尽早切页，不要硬套。
如果 Claude Status 此刻就在报事故
状态页应该排在第一位，因为它可以直接帮你省掉一轮没有价值的本地排查。如果 Claude Status 正在对 Claude API、Claude Code、登录或相关组件报红，那么当前最安全的动作通常就是停手等待，而不是继续折腾本地环境。
这个建议听起来简单，却最容易被忽视。因为报错发生在你的终端、你的仓库、你的账号里，人很容易本能地觉得问题也一定发生在自己这边。但只要实时事故还没恢复，继续改本地设置、切换路由、重登甚至重装，往往只会制造更多噪音。
这条分支里真正有价值的动作很少。保留精确错误文本，记下时间，以及任何 request_id。Anthropic 的 error 文档 说明，错误响应会带顶层 request_id，普通 API 响应也会带 request-id header。等状态恢复后，再回到之前那条同样失败的路径重试。只有同路径复验，才能告诉你事故是不是全部原因。
但这条分支不该吞掉整篇文章。如果状态已经稳定为绿，问题就不再是“Anthropic 现在是不是挂了”，而变成“我的这条路径在服务恢复后为什么还没有恢复”。到这里，你就应该回到下一条更窄的分支，而不是继续等待。
如果状态页是绿的，但同一路径还是报 529
状态页是绿的，不等于你该开始随机更改套餐、认证方式或本地设置。它只说明“实时事故”这条分支暂时可以往后放，不代表“过载”这个解释彻底失效。
这也是最让人烦躁的一条分支。官方错误码说是过载，公共状态页看起来又没问题，可你的终端还是继续失败。官方仓库里的 issue，比如 #3558 和 #3572，在这里很有价值，因为它们证明这种“状态页看起来正常，但 Claude Code 仍在重复 529”的场景确实存在。它们不能证明一种统一根因，但足以证明这不是读者自己的幻觉。
这时最正确的动作是一次有边界的同路径短重试。等一小段时间，用完全相同的路径、相同的请求再试一次，看看结果有没有变化。不要在这一轮里同时换模型、切套餐、改环境变量、重新登录再开新会话。那样一来，你虽然做了很多事，却失去了最关键的诊断价值: 你再也不知道原路径是不是自己恢复了。
很多人会在这条分支里做“看起来像大修”的动作，比如重装 Claude Code、先买更大的计划、或直接切别的路径。问题是，这些动作太大，信号太差。你真正想先回答的是更小的问题: 同一路径在短等待后有没有恢复？如果没有，它是不是已经稳定到值得升级支持？
如果短时间内多次同路径重试仍然失败，就别把 529 变成长篇本地折腾。保留证据，升级处理。绿色状态下，同一路径一再失败，本身就是一个比“Claude 好像很忙”更清晰的支持案例。
如果你其实走在 usage 或 API key 路径上
529 排障很容易跑偏，还有一个原因: 用户以为 Claude Code 一定在走自己想的那条认证路径。Anthropic 面向 Pro / Max 用户的帮助页明确写着，如果环境里设置了 ANTHROPIC_API_KEY，Claude Code 会优先使用这个 key，而不是你的订阅认证。光这一条，就能解释很多“我明明已经登录了，为什么还这样”的错判。
如果你以为自己在走 Pro / Max 订阅路径，但 shell 里其实导出了 ANTHROPIC_API_KEY，那就不要再把 529 先理解成订阅额度或 Claude 主服务的问题。先用 /status 配合环境变量确认活跃路径，再决定后面的解释。路径判断错了，后面的所有判断都会变形。
同样地，如果你在走代理、wrapper 或别的 provider route，第一步也不是立刻去“换一家试试”。更稳的做法，是先确认目标路径，清掉陈旧假设，再把同一个请求放回你原本想验证的路径上。如果移除意外的 API key 或切回预期路径后，529 消失了，那真正问题就是路径混淆；如果切回目标路径后仍然报 529，那么“过载”依旧是更好的解释。
这一节也要守住边界。如果最后暴露出来的根因其实是使用量耗尽、共享计划消耗异常、或 API tier 限制，那就去更适合的兄弟页，而不是硬把所有问题都装进 529。真实问题更像 fast drain 或 quota 行为时，可以继续看Claude Code 使用量异常诊断指南。如果真实症状是 500，那更适合跳去Claude Code API Error 500 指南。
修好之后怎么验证，什么时候该升级
529 的恢复速度，往往取决于你能不能把“有没有变化”换成“这条同一路径在一个明确动作后有没有恢复”。这就是为什么同路径验证这么重要。它同时帮你避免三件事: 盲目重试、无意识切分支、以及写不出任何有效信息的支持单。
在升级前，先从同一条失败路径里拿到最小但有用的证据包:
- 精确错误文本，包括
529或overloaded_error - 任何
request_id或request-id - 报错时 Claude Status 显示的状态
- 这是短重试后仍失败、路径切回预期后仍失败，还是你本来就落在错误路径上
- 最小复现步骤，或相关的
/status输出
这份清单故意写得很短。支持更需要一个干净的复现故事，而不是一份漫长的试错日记。比如，“绿色状态下，同一路径短退避后仍报 529，并附上 request_id”就很有用；“我改了很多东西还是不行”则几乎没法用。
升级边界同样应该很短: 如果状态核了、路径核了、同一路径做过一次有边界的短重试后仍然返回 529，就停止继续 improvisation。到这一步，问题已经不再是“我还能多试什么”，而是“我能不能把证据交得足够清楚”。
Frequently Asked Questions
Claude Code 的 API Error: 529 和 429 rate_limit_error 是一回事吗？
不是。Anthropic 的 API error 文档 把它们定义成两个不同错误类型。429 是限流分支，529 是过载分支。
为什么 Claude Status 是绿的，我还是会看到 529？
因为绿色状态页只能排除“实时事故”这条分支，不能保证你眼前这条 Claude Code 路径已经自动恢复。下一步应该是同路径短重试或路径核对，而不是随机改本地配置。
看到 529 以后，我应该立刻换套餐或买更多额度吗？
不应该把这当成第一步。529 首先表示过载，而不是你个人额度耗尽。先确认错误码和活跃路径，再决定是否要看套餐或用量。
如果我本来以为自己在走订阅路径，最该先检查什么？
先看 ANTHROPIC_API_KEY 有没有被设置，再配合 /status 和环境变量确认活跃路径。Anthropic 的帮助页明确说明，只要这个 key 存在，它就会覆盖订阅认证。
升级支持时到底该发什么？
发精确错误文本、任何 request_id、当时状态页情况、你测试的路径，以及最小复现步骤。目标不是讲完整故事，而是先减少歧义。
The Working Rule
Claude Code 的 API Error: 529 最适合被当成“先按过载恢复，再排除错误分支”的问题，而不是“先怀疑自己额度”的问题。先看状态，保持路径稳定，只做一个有边界的动作，在同一路径验证；如果仍失败，再带证据升级。