Claude API 调用失败诊断：从进程环境到最小复现

建立可复现的故障记录

先回答：哪一个环境失败、何时开始、所有请求还是某一种输入失败、最近改了什么？保存 SDK 版本、运行时版本、部署版本和脱敏请求形状。开发机成功而容器失败，优先比较环境变量、出站网络和代理；同一环境只有图片请求失败，优先检查载荷与内容块结构。不要一开始就更换模型、密钥、网络三个变量。

第一层：连接与凭据注入

没有 HTTP 响应时，区分 DNS、连接、TLS 和读超时；检查系统时间、组织代理与出口策略。不能关闭证书校验来“修复” TLS。普通网络探测成功也不能证明 Messages 请求已获授权。

在真正发请求的进程里检查环境变量是否存在，避免终端有值、服务进程没有值的误判。以下代码只报告配置状态，不输出前后缀、长度或完整值，也不擅自修剪和覆盖密钥。它不能证明密钥仍然有效。

import os

def inspect_configuration(env):
    key = env.get("ANTHROPIC_API_KEY", "")
    return {
        "key_present": bool(key),
        "key_has_surrounding_space": bool(key) and key != key.strip(),
        "model_configured": bool(env.get("CLAUDE_MODEL")),
    }

if __name__ == "__main__":
    print(inspect_configuration(os.environ))

第二层：把请求缩到最小

保留账号当前可用的模型 ID、正整数 max_tokens 和一条无敏感信息的 user 消息，暂时移除工具、图片、额外采样参数及复杂历史。使用官方 SDK 的 Messages 接口；system 使用独立字段，不照搬其他平台的消息格式。不要把旧文章里的模型白名单或统一输出上限写死。

如果最小请求成功，再一次只恢复一个功能：历史、文件、工具、流式、业务模板。首次恢复即失败的部分是调查线索，不等于最终根因。检查响应中的非文本内容块和 stop_reason，不能假设 content[0] 永远有 text。实际最小请求也可能产生费用，应先设预算。

第三层：区分资源、速率和部署故障

收到 401、403、402 时分别核对认证、权限、账单；400 结合错误字段查参数与支出设置；429 检查请求频率、输入输出 token 及支出上限，不盲目加并发。批处理也有自己的限制，不能当作绕过配额的通道。

对比容器与开发机的 base URL、SDK 依赖锁定、超时和代理设置。经过业务网关时，还要区分网关自行返回的 502/504 与上游错误。流已启动后断开，保存已收片段为“未完成”，不要直接作为最终答案展示。

实例与验收

例：本地分类器成功，上线后所有请求报 401。先在服务进程执行上面的布尔检查；若 key_present 为 false，就修复部署密钥注入，再重启相应进程并验证。若为 true，继续检查组织与密钥状态，不能仅凭布尔值认定凭据可用。

关闭调试期的敏感日志，添加超时、并发上限和有限重试。用假客户端模拟认证失败、限流、超时和中途流错误，验证日志不含密钥、前端不展示原始异常。本文示例只完成离线检查，没有执行付费请求，也不宣称能在固定时间定位所有故障。