Claude API 错误码速查：原因、重试条件与安全日志

先读三个字段，再决定下一步

排错时同时记录 HTTP 状态、error.type 和 request-id。状态码只能缩小范围，不能证明密钥被封、款项不足或服务全面宕机。官方返回的新错误字段可能增加，解析器应保留未知类型的安全兜底。连接失败没有 HTTP 状态，流式请求也可能在返回 200 后才出现错误事件，不能看到 200 就提交完整结果。

4xx：先修复条件，不能统一重发

400 表示请求格式或内容问题，也可能涉及自行设置的支出限制；检查必填字段、参数组合和模型能力。401 检查密钥是否正确注入及是否有效；403 检查资源权限。402 检查账单状态，404 检查端点和资源标识。不要把聊天订阅等级当成 API 权限。

409 表示资源状态冲突，应读取新状态并解决冲突；413 表示请求字节数过大，需要压缩或拆分，不能仅降低输出 token。429 要结合错误说明和限制页面判断：短期速率限制可排队等待，支出上限则不是睡几秒就会解除。

5xx 与超时：有限恢复，保留不确定性

500、529 等暂时性服务故障可在总截止时间内退避重试；504 或客户端超时应检查长请求、连接和代理超时。请求超时并不证明服务端完全没有处理过。官方 SDK 有自动重试机制，应用再套多层重试会放大调用数和费用；应由一个层级统一管理。

有 retry-after 时尊重服务端等待建议；否则按上限退避并加入随机抖动。对于退款、发邮件等业务动作，重试模型请求与重试工具动作必须分开，先核对动作是否已发生。不能依据错误码承诺固定恢复时间、成功率或一定免计费。

一个本地分类器示例

下面仅把状态分成操作建议，不发起网络请求，也不自动执行重试。429 特意返回“检查限制”，避免把月度支出上限误判成短暂拥堵。该代码已做本地语法和断言检查；真实调用仍需结合服务端错误内容、请求头及业务状态。

def next_action(status):
    if status == 429:
        return "inspect_limit"
    if status in {500,504,529}:
        return "bounded_retry_if_safe"
    if status == 409:
        return "reload_and_resolve"
    if status in {400,401,402,403,404,413}:
        return "fix_request_or_account"
    return "inspect_without_blind_retry"

assert next_action(401) == "fix_request_or_account"
assert next_action(429) == "inspect_limit"
assert next_action(529) == "bounded_retry_if_safe"

提交工单前检查

日志只留时间、模型配置标识、状态、请求 ID、耗时和重试次数。不要 echo 密钥，不记录完整请求头、客户原文或含签名的 URL。比如上传图片触发 413，应先记录请求体大小并缩小图片，再以脱敏样例复现；反复更换密钥并不能解决载荷过大。持续异常时核对官方状态页，并向支持提供请求 ID 与脱敏复现步骤。