Claude API 常见错误排查：401、429、5xx 和流式中断

先说结论

遇到 API 报错时，先保存现场，再判断错误类别。建议记录请求时间、协议类型、最终请求路径、模型标识、状态码、客户端版本、超时设置和脱敏后的错误内容。

401 通常从认证信息、请求头和协议匹配关系查起；429 要区分限流、额度和短时间重复请求；5xx 先保留服务端现场，避免连续重试；流式中断则要区分连接、代理、SSE 解析、客户端读取和服务端错误事件。状态码只是线索，不能单独证明根因，也不能说明重试后一定恢复。

一、先建立可复现记录

不要只记录“请求失败”。一份有用的故障记录应包含时间和时区、原生 Messages 或兼容协议、脱敏后的最终路径、模型标识、状态码、错误类型、客户端版本、代理和超时设置。响应体只保留排查所需结构，删除密钥、Cookie 和用户内容。

访问密钥属于敏感凭证，不应出现在公开仓库、截图、日志或文章示例中。开发、测试和生产环境分开保存配置，能够减少相互影响。Tokeness 可以作为兼容服务的中性示例，但实际字段仍应以当前服务配置为准。

二、固定基础排查顺序

每类错误都建议先走同一条路径：

1. 确认客户端读取到了预期配置，排除空格、换行、截断和旧配置残留。
2. 查看脱敏后的最终路径，确认版本路径没有遗漏或重复拼接。
3. 从当前模型列表复制模型标识，核对大小写、连字符和版本后缀。
4. 确认客户端选择的协议与请求体字段属于同一套规范。
5. 先用最少字段和短文本复现，再逐项恢复可选参数。
6. 每次只改一个变量，并保存修改前后的结果。
   不要同时更换凭证、模型、协议和客户端。一次改变多个条件，下一次结果就无法说明是哪一项产生了影响。

三、401：先查认证边界

401 通常表示认证失败，但认证失败不只可能由凭证本身造成。先检查客户端是否读取了正确的密钥，密钥是否完整、有效、未被停用，以及请求头名称是否符合当前协议。

原生 Messages 协议和 OpenAI 兼容协议的认证方式、请求字段和响应结构并不相同。不能只替换一个地址，就继续复用另一套客户端配置。还要检查旧进程缓存、不可见字符和工具默认配置。

排查 401 时，不要反复发送真实凭证。可以用脱敏日志确认“是否读取到凭证”“使用了哪种协议”“请求头名称是否正确”，但不要记录凭证内容。若密钥曾经出现在日志、截图或提交记录中，应先撤销并更换，再继续测试。

四、429：区分限流、额度和重复请求

429 常被简单理解为“请求太快”，实际还可能与并发上限、账户额度、单次请求频率或客户端重复提交有关。遇到 429，先保存响应头、错误体、请求时间和客户端并发设置，再核对使用日志中的请求数量。

如果响应信息明确提示频率限制，应降低并发并按提示使用有上限的退避。如果账户状态或额度异常，重试不能解决问题。同一请求短时间出现多条记录时，检查队列、超时重发和重复提交。原因不明确时，用同一协议和小请求单独复现。

退避应设置最大次数和最大等待时间，达到上限就停止并保留现场。对写入、扣费或其他有副作用的请求，重试前还要确认服务端是否已经接受，避免造成重复操作。固定间隔的无限循环既不能证明服务恢复，也会增加排查噪声。

五、5xx 和 529：先保留服务端现场

5xx 说明响应属于服务端错误分类，不代表一定是模型不可用。不同状态可能与服务异常、网关连接、暂时过载或请求条件有关，不能只凭状态码判断具体原因。

建议按下面的顺序处理：

1. 暂停连续重试，保存一次完整的脱敏请求和响应。
2. 使用同一协议、同一模型和同样的小请求复现。
3. 若小请求成功，回查原请求的上下文长度、工具字段、并发和超时；仍失败时整理现场供服务方定位。
   不要一看到 5xx 就立刻更换模型。更换模型会改变变量，只有在原配置和故障现场已记录后，比较结果才有意义。对暂时性错误可以进行有限次数退避，但每次重试都应记录结果，并设置明确的停止条件。

六、流式中断：按 SSE 阶段定位

流式响应通常通过 SSE 事件序列传输，客户端可能在收到部分文本后断开，流中也可能出现明确的 error 事件。半截输出不等于完整成功，连接中断也不等于服务端没有处理请求。

先做一次非流式对照，再分阶段检查：

如果非流式成功而流式失败，优先检查客户端读取实现、代理缓冲和超时设置。若两种方式都失败，则回到协议、模型和认证边界排查。修复后先用短文本验证，并确认服务端是否已经形成完整调用，再决定是否恢复原业务请求。

流式恢复不能套用统一规则。对于可重复的只读请求，可以在确认未完成后有限重试；对于有副作用的请求，应先使用请求标识、日志或业务状态确认结果，避免把断流误判为未执行。

总结

排查 Claude API 错误时，顺序比盲目重试更重要：先记录脱敏现场，再区分协议和错误类别，最后一次只修改一个变量。401 查认证边界，429 查限流、额度和重复提交，5xx 查服务端现场并限制重试，流式中断先做非流式对照，再按 SSE 阶段检查连接、代理和读取实现。