Claude Code 出现 500、连续 529 或“上面的响应可能不完整”时，不要把整段任务再贴一遍。报错只说明响应中断，不证明文件编辑、Shell 命令或外部写入都没有发生。盲目重发，可能把已经完成的 tool call 再执行一次。
正确顺序是：先分错误，等待对应服务路径恢复，再续接同一个会话，核对真实状态，最后才发送 continue。500 是 api_error；连续 529 是共享容量过载；中途断流则表示已完成 block 被保留，但最后一个 block 可能缺失。第三种才是“重复工作”风险最大的分支。
最容易误判的是 529。Claude Code 文档把重复 529 写成过载，不是你的个人用量上限，也不是应该先付费升级的信号。先按终端原文落到下面这张分支板。
| 终端原文 | 先当成什么 | 第一动作 | 同一路径如何验证 | 什么时候继续深入 |
|---|---|---|---|---|
输出开始前出现 500 | 服务端内部错误 | 看 Claude Status，短等 | 同会话、同认证路径、同模型 | 状态页无事故但同一路径仍失败 |
输出开始前连续出现 529 | 跨用户容量过载 | 看状态页并等待；任务允许时才考虑 /model | 同会话、同路径冷却后再试 | 状态和路径都核过仍重复 |
Server error mid-response、连接中断或 stream 停滞 | 部分回合已完成 | 不重贴任务；先读保留内容并核对状态 | 原会话续接，确认后才发 continue | 无法证明某个工具或外部写入是否完成 |
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-08-04 复核时，Claude Status 显示 Claude API 和 Claude Code 为 operational，历史页同时列出了 8 月 3 日已经解决的模型错误事故。这个时间点只能说明当时没有公开活动事故，不能证明读者现在的失败一定是本地问题。
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、套餐和计费动作。
先续接原会话，不要重新描述整项任务
Claude Code 当前的错误说明把“中途失败”单独列出。响应已经开始后发生 server error、连接关闭或 stream 停滞时，Claude Code 会保留此前完成的 block，丢弃被截断的最后一个 block，并提示重发可能让同一批工具调用执行两次。
如果界面还在，先读屏幕上保留的响应。看到已完成的文件修改、命令结果、测试输出或部署步骤时，把它当作需要核验的证据，不要直接当成“后续都完成了”。服务恢复后，也不要先发完整原任务，而是先完成状态核对，再在原会话发 continue。
如果进程已经退出，回到任务原来的项目目录：
bashclaude --continue claude --resume
claude --continue 续接当前目录最近的会话；claude --resume 打开会话选择器。官方会话管理文档说明，续接会恢复对话历史、tool call 和结果。这比新开会话后凭记忆复述“刚才做到哪里”可靠得多。
不要在两个终端同时续接同一个 session。消息可能交错写进同一份 transcript。确实需要尝试另一条路线时，用明确的 fork/branch，而不是让两个执行者同时面对同一工作树。
发 continue 前先做副作用盘点
对话记录只能说明 Claude 尝试了什么；工作树、进程和外部系统才说明实际发生了什么。按从本地到远端的顺序核对：
| 可能的副作用 | 核对证据 | 安全决定 |
|---|---|---|
| 直接文件编辑 | git status --short、git diff -- <path>、文件内容 | 保留或明确回退现有编辑，不再要求做一遍 |
| Shell 命令改了文件 | 工作树、生成文件、命令输出、时间戳 | 按“可能已完成”处理；checkpoint 未必记录 |
| 测试、构建、迁移仍在跑 | 终端、进程列表、锁文件、测试报告、迁移表 | 等待或明确停止，不启动第二份 |
| commit 或 branch 操作 | git status、当前分支、git log -1 --oneline | 从观察到的 Git 状态继续 |
| CI、部署、工单、API、数据库写入 | run/deployment/request ID、目标记录、幂等键 | 到真正 owner 核对，不能从断流推断失败 |
Git 仓库可以先做一轮只读检查：
bashgit status --short git diff --stat git diff git log -1 --oneline
这些命令不能证明远端状态。如果中断回合可能已经创建 PR、触发部署、写入数据库、发送消息或调用付款接口，就去对应系统查实际记录。新开一个本地会话不会取消已经被外部服务接受的操作。
核对完成后，可以在续接会话里发送一条有边界的指令：
text先总结中断回合里已经完成的 tool call，并与当前工作树和我提供的外部状态逐项核对。 不要重跑命令，也不要进行外部写入。只指出一个下一步，等我确认后再执行。
checkpoint 是局部撤销，不是事务日志
Claude Code 的 checkpoint会为直接文件编辑工具保存快照，并随会话保留，因此续接后仍可用 /rewind。它适合回退一段已确认错误的编辑。
它不跟踪 Bash 命令改动的文件，也不保证覆盖后台 subagent、并发手工编辑、链接路径，更不可能撤销部署、API、数据库、消息或付款。文件的长期历史仍要靠 Git，远端状态要靠对应平台的审计记录。
先确认要撤销什么，再 rewind。盲目回退后又盲目重跑，只会把“不确定”换成另一种重复。
限流分支：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 文案之后。
宕机后可以把同一任务再贴一次吗？
如果 Claude Code 提示响应可能不完整，就不安全。先续接同一会话，读保留 block，核对本地和远端状态，再发送有边界的 continue。
/rewind 能撤销 Shell 命令和部署吗？
不能。checkpoint 只覆盖受支持的直接文件编辑，不覆盖 Bash 和远端副作用。Git、进程、CI、部署、API 与数据库必须分别核对。
