Claude Code 同时出现 500、529 或“限流”字样时，先不要继续猛重试，也不要立刻改套餐。三个入口不是同一种故障：500 先看服务状态，重复 529 先按过载处理，429 或明确的用量窗口才进入限额排查。
最容易误判的是 529。Claude Code 文档把重复 529 写成过载，不是你的个人用量上限，也不是应该先付费升级的信号。先按终端原文落到下面这张分支板。
| 终端原文 | 先当成什么 | 第一动作 | 同一路径如何验证 | 什么时候继续深入 |
|---|---|---|---|---|
500 | 服务端内部错误 | 看 Claude Status，短等后同一命令重试一次 | 同命令、同认证路径、同模型 | 状态页无事故但同一路径仍失败 |
重复 529 | 容量过载 | 看状态页，短等；只有任务允许时才考虑 /model | 同会话、同路径冷却后再试 | 状态和路径都核过仍重复 |
429 | API key 或 provider 限流 | 看等待窗口、Console 限额、模型限额和实际 API 路径 | 等窗口变化或修正路径后再试 | header 或 Console 仍显示额度耗尽 |
Server is temporarily limiting requests、session limit、weekly limit | Claude Code 临时限流或用量窗口 | 冷却，或看套餐 / session 窗口 | 窗口变化后恢复同一工作流 | 文案明确写到套餐或重置窗口 |
| 套餐看起来不对，限额和账号不一致 | 路径覆盖 | 跑 /status，检查 ANTHROPIC_API_KEY 或代理 | 确认是否走了预期订阅或 API key 路径 | 清理路径后仍是同一错误分支 |
先分支，不要先猜原因
Claude Code 的错误说明把运行时错误映射到 Claude API 错误码，并且会在显示很多错误前先自动重试。这意味着你看到终端错误时，后台已经试过一轮，下一步不是“再试十次”，而是把错误分到正确分支。
500 要求你看状态页、短等、同一路径只重试一次；重复 529 要求你先按过载处理，不要先怀疑个人额度；真正的 429 要看 API key、provider、并发、模型和 retry-after；session 或 weekly limit 要看用量窗口；路径不一致则先查 /status 和环境变量。
2026-04-20 复核时，Claude Status 显示 Claude API 和 Claude Code 公开状态为 operational，但状态历史也有当天和 4 月 15 日的已解决事故。这个日期边界只能说明当时没有公开活动事故，不能证明读者现在的失败一定是本地问题。
500 分支：状态页、一小段等待、同命令一次
Anthropic 的 API 错误文档把 HTTP 500 映射为 api_error。Claude Code 错误说明也把 API Error: 500 Internal server error 归为基础设施侧问题，而不是你的 prompt、设置或账号本身造成的错误。
这个分支的安全动作很窄：
- 先看 Claude Status。
- 短等后只重试同一个命令或同一条消息一次。
- 验证时不要同时换模型、换路径、改环境变量。
- 状态页没有事故而同一路径仍失败时，保留请求细节，用
/feedback或支持路径升级。
如果你只看到持久的 API Error: 500，后续进入 Claude Code API Error 500 排查。当前分支只负责防止你把 500 错当成限流或 529。
529 分支：过载，不是你的用量上限
Claude Code 文档对重复 529 的边界很直接：API 暂时处在跨用户容量压力下，Claude Code 已经自动重试过，529 不是你的 usage limit，也不会计入 quota。
所以第一动作不是升级。更稳的顺序是：
- 看状态页是否有容量提示。
- 等几分钟再试。
- 只有任务能接受模型变化，并且容量信息支持时，才用
/model切换。 - 冷却后验证同一 session 和同一请求路径。
如果状态和路径都核过，重复 529 仍回来，再进入 Claude Code 529 过载错误排查。不要把 529 overloaded_error 写成 429 限流；这会把你带向错误的 key、套餐和计费动作。
限流分支：429、临时限制、套餐窗口要分开
“限流”在 Claude Code 里至少有三种含义。
第一种是真正的 API 429 rate_limit_error。这个分支属于 API key、provider 项目、模型限额、并发、RPM/ITPM/OTPM 和 retry-after。它应该进入 Claude Code token / rate limit 排查。
第二种是 Claude Code 的临时限制文案：Server is temporarily limiting requests (not your usage limit)。这个分支更像短暂节流，先冷却，再同一路径重试；它不是套餐耗尽的证据。
第三种是真正的用量窗口：session limit、weekly limit、Opus limit 或带 reset 时间的套餐窗口。这个分支属于 /usage、重置时间、套餐窗口和额外用量判断，可以继续看 Claude Code rate limit reached 或 Claude Code 用量限制诊断。
路径覆盖分支：先查认证，不要先怪套餐
Anthropic 的 Claude Code API key 帮助文档说明，环境变量里的 ANTHROPIC_API_KEY 优先级高于已登录的订阅认证，/status 可以显示当前认证方式。这让路径验证变成恢复流程的一部分。
当错误和你以为的账号权益不一致时，先做不泄露密钥的检查：
- 在 Claude Code 里运行
/status。 - 检查 shell 或环境中是否设置了
ANTHROPIC_API_KEY，不要把 key 粘贴到任何地方。 - 确认当前走的是订阅认证、Anthropic API、Bedrock、Vertex 还是代理路径。
- 回到你真正想验证的路径，再复跑同一个请求。
如果改正路径后错误变化，真实问题就是 route mismatch。若同一目标路径仍按原错误失败，你才有干净证据进入对应分支。
升级前先保存一份干净证据
Anthropic API 错误响应可能包含 request_id，响应 header 也可能有 request ID。Claude Code 还有 /status、/model、/usage、/feedback 这些分支工具。
升级前保存最小证据包：
- 终端原文，包括
500、529、429或完整限制文案； - 失败时间和时区；
- 当时 Claude Status 结果；
/status显示的活动路径；- 当前模型，以及是否改过
/model； - 同一路径重试结果；
- 可用的 request ID 或反馈上下文。
一旦分支匹配、最小动作完成、同一路径仍失败，就停止随机尝试。更多无边界重试只会破坏证据。
常见问题
Claude Code 529 是限流吗？
不是。重复 529 在 Claude Code 文档里是过载分支。真正的 API 限流是 429 rate_limit_error，临时限制和套餐窗口又是另外两条分支。
Claude Code API Error 500 第一件事做什么？
先看 Claude Status，短等，再用同一个命令或消息重试一次。状态页无事故且同一路径仍失败时，再带请求细节进入 500 深排或 /feedback。
状态页是绿色但 Claude Code 还是失败怎么办？
绿色状态只排除公开活动事故，不等于错误归你。继续看终端原文、活动认证路径、模型和同一路径验证结果。
怎么知道 API key 覆盖了订阅？
在 Claude Code 里运行 /status，再检查 shell 是否设置了 ANTHROPIC_API_KEY。环境变量 API key 可能优先于订阅登录。
看到 529 要升级套餐吗？
不要把升级当第一动作。重复 529 是过载分支，升级只应该发生在明确的套餐、session、weekly 或 usage window 文案之后。