如果 Claude Code 显示 API Error: 400 due to tool use concurrency issues，第一判断不是额度用完、状态页故障、API key 坏了，也不是简单地“你同时开了太多工具”。更稳的判断是：当前会话或你的 Anthropic Messages API 请求里，某个工具调用、工具结果或思考块的历史已经对不上。Claude Code 用户应先保存当前任务和错误文字，再用 /rewind 或连续按两次 Esc 回到损坏工具回合之前；自己实现工具调用的开发者，则要检查上一轮 assistant 的 tool_use 和下一条 user message 里的 tool_result 是否一一匹配，并且结果块是否排在文字之前。
| 使用场景 | 先检查的责任方 | 第一安全动作 |
|---|---|---|
| Claude Code CLI | 会话里的工具/思考历史断裂 | 保存上下文，执行 /rewind 或 Esc 两次，再用一个简单工具动作验证 |
| VS Code、Cursor 或其他 IDE 集成 | 扩展或客户端保存的历史不一致 | 对比 CLI 与 IDE 的同一个小工具动作，不先卸载或降级 |
| 自建 Anthropic API 客户端 | tool_result 序列化错误 | 每个 tool_use_id 都要有结果，所有结果放在同一条 user message，并在文字之前 |
| 其他 400 文案 | 请求 schema、role、system 或 extra input 错误 | 按实际校验错误处理，不套用并发修复 |
| 429、529、500、连接、认证、账单 | 另一类 Claude 错误 | 进入额度、过载、服务端、网络或账号分支 |
先不要轮换 key、购买额度、切换服务商或把问题归咎于 Anthropic 全局故障。Claude Code 的验证方式很简单：回退后让它读一个文件、列一个目录或跑一个短命令；API 客户端的验证方式则是打印脱敏后的 message shape，确认所有工具结果在正确位置。
这个 400 到底是什么意思
“tool use concurrency issues” 听起来像并发数量太多，但在这个错误里，更重要的是工具历史的结构是否完整。Claude Code 的错误参考把这类报错放在 tool use 或 thinking block mismatch 下面；Claude API 的 400 又属于请求格式或内容不合法。两条线合在一起，说明服务器拒绝的不是你的业务目标，而是下一次请求携带的对话状态。
这种状态断裂通常有两个入口。第一种是 Claude Code 会话很长，中途停止过工具调用，IDE 扩展保存了半截状态，或者用户编辑/压缩过对话，导致后续请求还带着无法配对的工具或思考块。第二种是你自己在写 API 客户端：上一轮 assistant 发出了一个或多个 tool_use，但下一轮 user 没有一次性返回所有对应 tool_result，或者把普通文字放在结果块前面。
这也是为什么正常聊天有时还能继续，而文件读取、编辑、bash、搜索这类工具动作会失败。纯文本对话不需要同样严格的工具结果配对；工具调用需要 ID、顺序、角色和块类型同时正确。把它当作普通坏请求、额度问题或网络问题，会让你在错误分支上浪费时间。
先恢复 Claude Code 会话，不要直接清空
Claude Code 用户最应该避免的是一上来就 /clear 或新开会话，然后把整段旧对话复制进去。这样可能把损坏的工具历史也复制过去。更稳的做法是先保存人工可读的信息：当前任务、相关文件、刚刚执行的工具动作、完整错误文字、出错时间、普通聊天是否还能回答，以及你是在 CLI 还是 IDE 里看到它。
然后确认使用面。CLI 里报错，就看 Claude Code 版本是否明显落后，并记录当前命令行环境。IDE 里报错，就用 CLI 做一个相同的小动作，例如只读一个无敏感文件或列出当前目录。如果 CLI 可以工作而 IDE 失败，先把工作迁回 CLI，保留扩展侧错误证据，再处理扩展版本或配置；如果 CLI 和 IDE 在同一个会话里都失败，就优先回退会话，而不是把扩展当作唯一原因。
回退时先用 /rewind。Claude Code 也记录了连续按两次 Esc 可以退回到前一段对话状态。回退后不要马上要求它同时读文件、修改代码、运行测试和搜索文档；用一个很小的动作验证工具层是否恢复。通过后再给一个干净、单一的继续指令，把任务往前推进。
如果回退后同一个简单工具动作仍然失败，再考虑新会话。新会话只带任务摘要、涉及文件、最后可信状态和脱敏错误证据。不要带工具调用 transcript，不要带 API key，不要粘贴私有文件内容，也不要把失败前后的完整日志作为 prompt 塞进去。你要保留的是工作上下文，不是导致 400 的机器历史。
IDE、Cursor、VS Code 里的报错要单独分流
IDE 分支容易误判，因为用户看到的往往是“普通问答还能聊，工具一动就 400”。这并不证明你真的同时调用了多个工具；它也可能是扩展保存的会话历史、终端桥接、远程环境或本地客户端版本把工具结果发错了。
排查顺序应保持克制。先记录 surface：Claude Code CLI、VS Code、Cursor、远程 SSH、WSL、终端复用器，还是某个包装器。再比较同一个小工具动作在 CLI 和 IDE 中的表现。第三步才看版本、重启扩展、重启 IDE 或更新 Claude Code。降级某个旧版本可以是历史讨论里的临时绕法，但不应该变成当前通用答案。
如果 IDE 失败而 CLI 成功，说明可以先把交付工作放回 CLI，避免因为扩展状态坏了而清掉整个任务。如果 CLI 也失败，优先回退当前 Claude Code 会话。只有当新的干净会话、同一小工具动作、同一版本环境仍复现时，才适合把证据提交给维护者。
中文环境里常见的另一个误区是把“重新登录”“重新授权”当成第一步。认证会话确实可能导致某些请求异常，但这个精确 400 的核心仍然是工具历史结构。除非错误文案明确指向 auth、billing 或 token，否则登录动作只能作为旁路检查，不能替代 /rewind 与 message shape 检查。
自己调用 Anthropic API 时，检查 message shape
如果你在写代理、插件、IDE 集成或后端工具 runner，这个错误更可能藏在 messages 数组里。关键规则有三条：assistant 发出的每个 tool_use.id 都要收到一个匹配的 tool_result.tool_use_id；同一轮 assistant 发出的多个工具结果，要放进下一条 user message 里一起返回；如果这条 user message 同时包含文字和工具结果，工具结果必须在文字之前。
健康的结构可以这样理解：assistant 说“我要调用 read_file 和 grep”；你的程序可以并行执行，也可以顺序执行；但回给模型时，下一条 user message 里必须同时包含 read_file 的结果和 grep 的结果。不能先发一个结果，再等下一条 user message 发另一个；不能先写“我已经拿到结果”，然后再放 tool_result；也不能丢掉其中一个 ID。
| 常见错误 | 为什么会触发 400 | 修复方式 |
|---|---|---|
少回一个 tool_result | assistant 发出的工具请求没有闭环 | 为每个 tool_use_id 返回一个结果，或从回放历史中移除整轮损坏工具调用 |
| 把多个结果拆成多条 user message | API 需要下一条 user message 承接整组结果 | 把同一 assistant turn 的所有结果合并到一条 message |
普通文字排在 tool_result 前面 | 工具结果块必须优先出现 | 先放所有 tool_result，再放允许存在的说明文字 |
| 压缩历史时删掉旧工具块 | 回放历史看似短了，但配对关系断了 | 压缩器必须保留或完整移除工具调用与结果整组 |
调试时不要记录密钥、token、私有文件内容或客户数据。你需要的是形状证据：role 顺序、content block 类型、工具 ID、结果数量、结果所在 user message，以及是否有文字插在结果前面。这些字段足以定位 serializer 问题。
并行执行可以存在，结果返回必须严格
真正的并行工具调用并不是被禁止的。Claude 可能在一轮 assistant message 里发出多个工具请求，客户端也可以并发执行这些请求。问题在于“执行方式”和“回传方式”不是同一件事：执行可以并发，回传必须按 Anthropic 要求保持一个完整的结果集合。
因此，把修复方案写成“以后不要并发”并不够。如果你的 serializer 会丢 ID、拆 message、把总结文字放在工具结果前面，哪怕你实际是一个工具一个工具顺序执行，也仍然会失败。相反，如果你能正确收集所有结果并一次性按 ID 返回，多个工具并行执行也可以是有效路径。
disable_parallel_tool_use 只适合解决真实客户端限制，例如工具有副作用、外部系统不能并发写入，或你当前 runner 还没有可靠的多工具结果收集器。它不是 message shape 的替代品。即使只有一个工具调用，也必须让它的结果紧跟上一轮 assistant 的工具请求，并且用正确的 role 和 block 类型返回。
生产客户端最好在工具 runner 边上加一个 transcript validator：检查每个 assistant tool_use.id 是否在下一条 user message 中出现；检查是否有多余 tool_result；检查同一轮结果是否被拆散；检查 tool_result 是否排在文字之前；检查历史压缩是否删掉了仍被模型状态依赖的工具、结果或思考块。
为什么长会话、中断和压缩会让它复发
这个错误常在会话跑了很久以后出现，因为工具历史不是普通聊天记录。普通聊天可以摘要、删减、改写；工具历史有配对、ID、顺序和连续性。一次停止的工具调用、一段被截断的流式响应、一个 IDE 扩展的旧缓存、一次手工删改，都可能让下一次请求带着无法解释的半截状态。
复发时不要只问“是不是又并发了”。先问这次请求前发生了什么。是否按下过停止？是否修改过历史？是否把旧 transcript 贴进新会话？是否让代理框架压缩了 messages？是否只保留自然语言摘要，却丢了工具结果块？是否在同一会话里切换了工具集合或 server tool 配置？
| 复现场景 | 高风险点 | 更稳的处理 |
|---|---|---|
| 停止过一次工具运行 | 历史里留下半个工具回合 | 回退到该工具调用之前，再用小动作验证 |
| 手工编辑或压缩 messages | 必需的工具或思考块被删掉 | 从人工摘要重启，不复制损坏历史 |
| 只有 IDE 工具失败 | 扩展状态或桥接层保存错误 | 对比 CLI，记录版本和最小失败动作 |
| 自建客户端回放旧消息 | serializer 丢 ID、错顺序或拆结果 | 打印脱敏 message shape 并验证配对 |
如果你只是不断让模型“再试一次”“慢一点”“不要同时调用工具”，它可能偶尔绕过去，但不会修复已经损坏的历史。能稳定解决问题的，是回到损坏回合之前，或让 API 请求重新满足工具结果协议。
不是所有 Claude 400 都走这个分支
精确错误文字很重要。API Error: 400 due to tool use concurrency issues 可以进入工具历史分支；其他 400 可能完全不同。例如 Cursor 或某些包装器可能显示 extra inputs、unsupported role、system message 不支持、JSON 结构错误、模型参数错误等。这些都属于请求格式问题，但修复点不在 /rewind 或工具结果配对。
| 症状 | 更合适的分支 |
|---|---|
| 400 加 extra inputs、unsupported role、invalid system 或 malformed JSON | 请求 schema / 参数校验 |
| 400 出现在工具调用、编辑历史或长会话之后 | 工具结果或思考块历史不一致 |
| 429 或 rate limit reached | 额度、限流、模型压力、workspace 或 provider quota |
| 529 overloaded_error | Anthropic 容量压力与有界重试 |
| 500、504 | 服务端错误、超时、request_id 与状态检查 |
API Error: Connection error | 网络、代理、VPN、DNS、TLS 或 SDK timeout |
| auth、billing、credits 文案 | 账号、项目、组织、支付或凭证 |
状态页仍然有价值，但它不是这个错误的第一证据。2026 年 7 月 4 日保存的 Claude Status 快照显示 Claude API 与 Claude Code 运行正常；这只能说明当时没有显著全局事故，不能证明你的本地会话、IDE 扩展或 messages 数组健康。遇到大面积同时失败时可以查状态页；回到这个精确 400 时，仍然要检查会话历史和工具结果顺序。
提交 issue 或工单前，先留下证据包
一个可行动的证据包不需要泄露隐私。它应该包含 Claude Code 版本、IDE 或扩展版本、运行表面、完整错误文字、时间和时区、触发动作类型、普通聊天是否还能工作、/rewind 或 Esc 两次是否恢复、CLI 与 IDE 对比结果，以及自建 API 客户端的脱敏 message shape。
不要上传 API key、token、私有文件、客户数据、完整 proprietary transcript 或未脱敏日志。对维护者最有用的是结构：上一轮 assistant 是否发出一个或多个工具调用，下一条 user message 是否一次性回了所有结果，结果是否排在文字之前，是否存在缺失或多余 ID。
同一份证据也能帮助你预防复发。保留工具调用与结果整组，不要手工删改旧工具回合，不要把自然语言总结插在 tool_result 前面，不要把一轮工具结果拆成多条 message，不要把绿色状态页当作请求 shape 正确的证明。如果必须开新会话，只带任务摘要和安全文件引用。
FAQ
我应该先 /rewind、Esc 两次、/clear，还是新开会话？
先用 /rewind 或 Esc 两次，因为它们尽量回到损坏工具回合之前，同时保留更多有效上下文。/clear 或新会话应放在回退失败之后。新会话只带任务摘要，不带工具-heavy transcript。
普通聊天能回答，为什么读文件或编辑就失败？
普通聊天不需要工具结果配对；文件读写、bash、搜索和编辑都依赖工具状态。只要工具状态里的 ID、顺序或 block 类型对不上，工具动作就会失败，而文本回答仍可能继续。
这是不是说明我同时调用了太多工具？
不一定。它可能发生在真正的多工具回合之后，也可能发生在中断、编辑、压缩、扩展缓存、缺失结果、拆分结果或文字放在结果前面之后。修复目标是工具 transcript，不只是降低并发。
要不要换 API key？
这个精确错误不应该先换 key。新的 key 不会修复损坏的 message history。只有错误文案、账号状态或请求证据指向认证问题时，才进入凭证分支。
要不要禁用 parallel tool use？
只有当客户端确实管理不了多工具结果，或外部工具不能安全并发时才禁用。禁用后仍然要满足结果顺序规则：每个工具调用都有匹配结果，结果紧跟上一轮工具请求，并在文字之前。
Claude Status 还需要看吗？
需要，但只是旁路 sanity check。如果多个路线同时失败，查状态页可以排除大规模事故；如果错误仍然是这个 400，恢复重点还是 /rewind、会话历史和 tool_result 序列化。
提交 GitHub issue 或 support ticket 应该写什么？
写版本、使用表面、完整错误文字、时间、触发动作、普通聊天是否可用、/rewind 是否有效、CLI 与 IDE 对比、以及脱敏 message shape。不要贴 key、token、私有文件或完整机密 transcript。
什么时候放弃抢救当前会话？
在回退后，同一个小工具动作仍连续失败一两次，就不要继续把损坏历史往前推。保存证据，用人工摘要开干净会话，再把需要的文件和任务状态带过去。
