使用 Claude API 时，失败调用在所难免——参数错误、认证问题、限流，或者网络中断都可能发生。但大多数开发者遇到问题才会意识到一个尴尬的现实：日志里没有关键信息，根本无法排查。

本文换个角度来看这个问题：与其等错误发生后再被动补救，不如在系统设计时就规范日志字段，为将来的故障排查打好基础。这是从"事后救火"到"事前预防"的转变。

为什么需要统一的失败日志规范？

想象这个场景：用户反馈 API 调用失败，你打开应用日志一看，只有一条：“Error: Invalid request”。然后你得逐一排查：是参数有问题还是 Key 过期了？限流了还是服务故障？这种排查往往要花费数十分钟，甚至可能找不到根本原因。

反过来，如果日志中有 request_id、error_type、http_status_code、model、api_key_prefix 这些字段，你只需扫一眼就能 3 秒钟判断出问题类型。

统一日志规范的好处很明显：

• 快速定位问题：有标准字段支持，排查效率能提升 10 倍
• 可复用资产：日志规范设计一次，后续反复使用，长期收益大
• 团队协作：所有人都按同一套规范记录，理解成本低，沟通顺畅
• 可观测性：基于结构化日志能构建监控告警，提前发现问题苗头

日志字段完整分类模型：必需/推荐/可选

开发者常陷入一个误区：要么懒得记日志，要么记的日志冗余太多。正确的做法是按优先级分三个层级来设计。

必需字段：排查任何错误都离不开的 10 个核心字段

这些字段是诊断问题的最低要求。缺少其中任何一个，问题排查都会陷入瞎子摸象的局面：

字段名	数据类型	来源与获取方式	为什么必需
timestamp	毫秒级时间戳（Long）	本地系统时间	关联业务日志、追踪时间顺序
trace_id	字符串	业务侧生成的唯一标识	贯穿整个请求链路，关联多个子调用
request_id	字符串	HTTP 响应头 x-request-id	Claude API 侧的唯一标识，排查时的金钥匙
http_status_code	整数	HTTP 响应状态码	快速判断错误大类（4xx 是客户端错，5xx 是服务端错）
error_type	字符串	响应 JSON 的 error.type 字段	精确错误分类（比如 invalid_request_error、authentication_error）
error_message	字符串	响应 JSON 的 error.message 字段	人类可读的错误详情
model	字符串	请求参数中的 model 值	不同模型可能有不同限制，有助于区分问题根因
endpoint	字符串	实际请求的 URL	区分官方 API 还是第三方中转，排查路由问题
client_sdk_version	字符串	SDK 内部版本号（如 anthropic-sdk-python==0.28.0）	SDK 版本差异导致的问题识别
sdk_language_runtime	字符串	运行时信息（如 Python 3.11、Node.js 18.16.0）	运行环境问题排查

取值示例（400 invalid_request_error 场景）：

{
  "timestamp": 1704067200123,
  "trace_id": "order_20240101_user123_req1",
  "request_id": "req_018EeWyXxfu5pfWkrYcMdjWG",
  "http_status_code": 400,
  "error_type": "invalid_request_error",
  "error_message": "messages: text content blocks must be non-empty",
  "model": "claude-3-5-sonnet-20241022",
  "endpoint": "https://api.anthropic.com/v1/messages",
  "client_sdk_version": "anthropic-sdk-python==0.28.0",
  "sdk_language_runtime": "Python 3.11.5"
}

推荐字段：大多数问题诊断都用得上的 12 个字段

这些字段在 70% 以上的故障排查中都有帮助，系统允许的话建议都记录：

字段名	数据类型	用途说明
api_key_prefix	字符串	仅记录 API Key 前 8 字符（如 sk-ant-...），用于区分多 Key 场景，绝对不要记完整 Key
messages_count	整数	messages 数组长度，诊断输入参数问题
tools_count	整数	tools 数组长度，某些错误与工具定义有关
max_tokens_requested	整数	请求的 max_tokens 参数，部分错误与此有关
temperature	浮点数	温度参数值，记录请求配置
response_time_ms	整数	调用耗时（毫秒），用于性能问题诊断
retry_count	整数	重试次数，识别是否触发重试逻辑
retry_reason	字符串	重试原因（比如 429_rate_limit、5xx_server_error、timeout）
request_headers_hash	字符串	请求 Header 的 SHA256 摘要，便于对比不同请求，避免存储完整内容
request_body_hash	字符串	请求体的 SHA256 摘要（仅 hash，不存原文），用于快速对比问题请求
stream_mode	布尔值	是否流式调用（true/false），流式场景的错误处理逻辑不同
content_types_in_messages	数组	messages 中内容类型列表，如 ["text", "image_base64"]

推荐字段取值示例（429 rate_limit_error 场景）：

{
  "timestamp": 1704067200123,
  "trace_id": "order_20240101_user123_req2",
  "request_id": "req_018EeWyXxfu5pfWkrYcMdjWH",
  "http_status_code": 429,
  "error_type": "rate_limit_error",
  "error_message": "Rate limit exceeded: 10000 requests per minute",
  "model": "claude-3-5-sonnet-20241022",
  "api_key_prefix": "sk-ant-...",
  "messages_count": 3,
  "max_tokens_requested": 1024,
  "temperature": 0.8,
  "response_time_ms": 145,
  "retry_count": 2,
  "retry_reason": "429_rate_limit",
  "stream_mode": false,
  "content_types_in_messages": ["text"]
}

可选字段：特定场景需要的 9 个字段

这些字段主要用于多用户系统、有网络代理，或需要精细化监控的场景：

• user_id / user_id_hash：用户标识（有隐私需求的话用 hash）
• business_module：业务模块标识（如 chat_service、search_service）
• client_ip：客户端 IP，用于地域问题诊断
• proxy_used：是否使用代理及代理类型（如 nginx_reverse_proxy）
• output_tokens_estimated：估算输出 token 数（某些情况 API 会在错误中返回）
• custom_headers：自定义 Header 字典（如 {"x-request-version": "v2", "x-feature-flag": "new_api"}）
• stream_chunks_received：流式响应已接收的 chunk 数（仅流式调用）
• error_param：错误关联的参数路径（如 messages.1.content.0.text，来自响应 JSON）
• request_attempts_log：详细的重试尝试记录（仅在重试次数 > 0 时），记录每次尝试的时间与原因

按错误类型给出日志记录示例

不同的错误有不同的特征，理解这些特征有助于构造更有针对性的日志。

400 invalid_request_error：参数校验失败

常见原因：messages 结构不合法、tools schema 格式错、max_tokens 超限

{
  "timestamp": 1704067200000,
  "trace_id": "chat_20240101_user456_call1",
  "request_id": "req_018EeWyXxfu5pfWkrYcMdjWG",
  "http_status_code": 400,
  "error_type": "invalid_request_error",
  "error_message": "messages: text content blocks must be non-empty",
  "error_param": "messages.1.content.0.text",
  "model": "claude-3-5-sonnet-20241022",
  "endpoint": "https://api.anthropic.com/v1/messages",
  "messages_count": 2,
  "tools_count": 0,
  "response_time_ms": 145,
  "client_sdk_version": "anthropic-sdk-python==0.28.0"
}

诊断要点：看 error_param 字段就能精确定位出问题的参数。

401 authentication_error：认证失败

常见原因：API Key 过期、Key 不匹配、Key 被删除

{
  "timestamp": 1704067200000,
  "trace_id": "api_20240101_user789_call2",
  "request_id": "req_018EeWyXxfu5pfWkrYcMdjWH",
  "http_status_code": 401,
  "error_type": "authentication_error",
  "error_message": "Invalid authentication token",
  "model": "claude-3-5-sonnet-20241022",
  "api_key_prefix": "sk-ant-...",
  "endpoint": "https://api.anthropic.com/v1/messages",
  "response_time_ms": 89,
  "client_sdk_version": "anthropic-sdk-python==0.28.0"
}

诊断要点：api_key_prefix 帮你快速判断是哪个 Key 出问题；然后检查 Key 是否过期或环境变量是否正确注入。

429 rate_limit_error & 529 overloaded_error：限流/超载

常见原因：时间窗口内请求过多、服务过载

{
  "timestamp": 1704067200000,
  "trace_id": "batch_20240101_user123_call3",
  "request_id": "req_018EeWyXxfu5pfWkrYcMdjWI",
  "http_status_code": 429,
  "error_type": "rate_limit_error",
  "error_message": "Rate limit exceeded: 10000 requests per minute",
  "model": "claude-3-5-sonnet-20241022",
  "response_time_ms": 250,
  "retry_count": 2,
  "retry_reason": "429_rate_limit",
  "stream_mode": false,
  "client_sdk_version": "anthropic-sdk-python==0.28.0",
  "custom_headers": {
    "retry-after": "60"
  }
}

诊断要点：看 retry_count 了解自动重试是否生效；retry-after Header 告诉你需要等待多久；如果 429 频繁出现，需要调整请求频率或申请增加额度。

5xx 服务端错误 & timeout：服务故障或网络超时

常见原因：Claude API 服务中断、网络延迟、代理超时

{
  "timestamp": 1704067200000,
  "trace_id": "prod_20240101_user234_call4",
  "request_id": "req_018EeWyXxfu5pfWkrYcMdjWJ",
  "http_status_code": 500,
  "error_type": "internal_server_error",
  "error_message": "Internal server error",
  "model": "claude-3-5-sonnet-20241022",
  "endpoint": "https://api.anthropic.com/v1/messages",
  "response_time_ms": 30000,
  "stream_mode": false,
  "retry_count": 3,
  "retry_reason": "5xx_server_error",
  "client_sdk_version": "anthropic-sdk-python==0.28.0",
  "proxy_used": "nginx_reverse_proxy"
}

诊断要点：response_time_ms 告诉你是客户端超时还是真的得到了 500 响应；如果有代理，需要检查代理日志来区分是代理故障还是后端故障；retry_count > 0 说明重试逻辑有效。

200 OK 但流式响应中断：隐蔽型失败

这种情况最容易被忽视——HTTP 返回 200，但 SSE 流在传输中断开了。

{
  "timestamp": 1704067200000,
  "trace_id": "stream_20240101_user345_call5",
  "request_id": "req_018EeWyXxfu5pfWkrYcMdjWK",
  "http_status_code": 200,
  "stream_mode": true,
  "stream_chunks_received": 5,
  "stream_error_occurred": true,
  "error_type": "stream_interrupted",
  "error_message": "connection closed unexpectedly after 5 chunks",
  "model": "claude-3-5-sonnet-20241022",
  "response_time_ms": 3200,
  "client_sdk_version": "anthropic-sdk-python==0.28.0",
  "custom_headers": {
    "connection": "closed"
  }
}

诊断要点：这是常被忽视的坑——流式调用时，200 响应码不代表成功，必须额外记录 stream_error_occurred 和 stream_chunks_received 字段来标识真实状态。

SDK 语言特定实现

理论上知道要记什么，还得知道如何从 SDK 响应对象中提取这些字段。

Python SDK (anthropic >= 0.27.0)

import json
import logging
import time
from anthropic import Anthropic, APIError

logger = logging.getLogger(__name__)
client = Anthropic(api_key="sk-ant-...")

def log_failed_call(error, start_time, trace_id):
    """从异常对象中提取日志字段"""
    elapsed_ms = (time.time() - start_time) * 1000
    
    log_data = {
        "timestamp": int(time.time() * 1000),
        "trace_id": trace_id,
        "response_time_ms": int(elapsed_ms),
    }
    
    # 从 API 错误对象提取字段
    if hasattr(error, 'response'):
        log_data["request_id"] = error.response.headers.get("x-request-id", "unknown")
        log_data["http_status_code"] = error.status_code
        
    if hasattr(error, 'error'):
        log_data["error_type"] = error.error.type
        log_data["error_message"] = error.error.message
        if hasattr(error.error, 'param'):
            log_data["error_param"] = error.error.param
    
    logger.error(json.dumps(log_data))

# 调用示例
try:
    start_time = time.time()
    response = client.messages.create(
        model="claude-3-5-sonnet-20241022",
        max_tokens=1024,
        messages=[{"role": "user", "content": "Hello"}]
    )
except APIError as e:
    log_failed_call(e, start_time, trace_id="order_20240101_user123")

TypeScript SDK (sdk >= 0.16.0)

import Anthropic from "@anthropic-ai/sdk";
import { APIError } from "@anthropic-ai/sdk/error.mjs";

const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });

async function logFailedCall(error: any, startTime: number, traceId: string) {
  const elapsedMs = Date.now() - startTime;
  
  const logData: Record<string, any> = {
    timestamp: Date.now(),
    trace_id: traceId,
    response_time_ms: elapsedMs,
  };
  
  // 从错误对象提取字段
  if (error instanceof APIError) {
    logData.request_id = error.headers?.["x-request-id"] || "unknown";
    logData.http_status_code = error.status || null;
    logData.error_type = error.error?.type || error.name;
    logData.error_message = error.message;
  }
  
  console.error(JSON.stringify(logData));
}

// 调用示例
try {
  const startTime = Date.now();
  const response = await client.messages.create({
    model: "claude-3-5-sonnet-20241022",
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello" }],
  });
} catch (error: any) {
  logFailedCall(error, Date.now(), "order_20240101_user123");
}

日志格式建议与多语言集成

完整的失败调用日志模板

{
  "timestamp": 1704067200123,
  "trace_id": "order_20240101_user123_req1",
  "request_id": "req_018EeWyXxfu5pfWkrYcMdjWG",
  "http_status_code": 400,
  "error_type": "invalid_request_error",
  "error_message": "messages: text content blocks must be non-empty",
  "error_param": "messages.1.content.0.text",
  "model": "claude-3-5-sonnet-20241022",
  "endpoint": "https://api.anthropic.com/v1/messages",
  "api_key_prefix": "sk-ant-...",
  "client_sdk_version": "anthropic-sdk-python==0.28.0",
  "sdk_language_runtime": "Python 3.11.5",
  "messages_count": 2,
  "tools_count": 0,
  "max_tokens_requested": 1024,
  "temperature": 0.8,
  "response_time_ms": 145,
  "retry_count": 0,
  "stream_mode": false,
  "content_types_in_messages": ["text"],
  "request_headers_hash": "sha256:abc123def456",
  "request_body_hash": "sha256:xyz789uvw012"
}

Python logging 集成示例

import json
import logging
import time
from pythonjsonlogger import jsonlogger

# 配置 JSON 格式日志
logHandler = logging.StreamHandler()
formatter = jsonlogger.JsonFormatter()
logHandler.setFormatter(formatter)
logger = logging.getLogger("claude_api")
logger.addHandler(logHandler)
logger.setLevel(logging.INFO)

# 记录失败调用
log_data = {
    "timestamp": int(time.time() * 1000),
    "trace_id": "order_20240101_user123",
    "http_status_code": 400,
    "error_type": "invalid_request_error",
    # ...其他字段
}
logger.error("Claude API call failed", extra=log_data)

敏感信息脱敏策略

日志中包含的数据可能涉及隐私或安全，必须有明确的脱敏规则。

敏感字段	脱敏策略	示例
API Key	仅记录前 8 + 后 4 字符，中间用 * 替代	sk-ant-*****-W6sD
messages 完整内容	不记录，仅记录 count 和 content_types	记 "messages_count": 3, "content_types": ["text", "image"]
tools schema 完整定义	不记录，仅记录工具名称	记 "tool_names": ["get_weather", "search"]
user_id（涉及用户隐私）	如非必要，记录 SHA256 hash	"user_id_hash": "sha256:abc123..."
response 内容	不记录，仅记录 token 计数和类型	记 "output_tokens": 512, "response_content_types": ["text"]

脱敏实现示例：

def sanitize_log_data(log_dict):
    """对日志进行脱敏处理"""
    if "api_key" in log_dict:
        key = log_dict["api_key"]
        log_dict["api_key_prefix"] = key[:8] + "*" * 16 + key[-4:]
        del log_dict["api_key"]
    
    if "messages" in log_dict:
        log_dict["messages_count"] = len(log_dict["messages"])
        del log_dict["messages"]
    
    if "user_id" in log_dict:
        import hashlib
        user_id = log_dict["user_id"]
        log_dict["user_id_hash"] = "sha256:" + hashlib.sha256(
            user_id.encode()).hexdigest()
        del log_dict["user_id"]
    
    return log_dict

基于日志的故障分析与监控

日志的价值不止在排查问题，还在于衍生出可观测性指标。

核心监控指标

根据日志字段，你可以构建这些关键指标：

• 错误率：按小时统计 error_type != null 的请求占比
• 错误分布：按 error_type 分组，识别最频繁的问题类型
• 模型性能差异：对比不同 model 的错误率和响应时间
• 重试成功率：计算 retry_count > 0 但最终成功的比例
• 限流压力：按时间段统计 error_type == "rate_limit_error" 的发生频率

告警规则示例

# 5 分钟内错误率 > 5%，则告警
if error_count / total_count > 0.05:
    alert("High error rate detected")

# 连续 10 次 5xx 错误，则告警
if consecutive_5xx_count >= 10:
    alert("Service degradation: multiple 5xx errors")

# 429 错误频繁（1 分钟内 > 100 次），需要限频
if rate_limit_errors_per_minute > 100:
    alert("Rate limit pressure increasing")

常见错误案例与日志对应关系

通过实际案例了解如何从日志快速诊断问题。

案例一：Tools Schema 错误

症状：用户报告"工具调用失败"

从日志看什么：

• error_param 包含 tools 路径 → 问题在工具定义
• error_message 包含 “schema” 关键字 → 确认是 schema 格式问题
• tools_count > 0 且 tools_count 与预期不符 → 确认工具列表

{
  "error_type": "invalid_request_error",
  "error_message": "tools.0.function.parameters: must be a dict",
  "error_param": "tools.0.function.parameters",
  "tools_count": 3
}

案例二：流式响应中断

症状：日志中看到部分响应，不知道是不是完整的

从日志看什么：

• stream_mode: true 且 stream_error_occurred: true → 确认流式中断
• stream_chunks_received 值较小（如 5）→ 推断在哪个阶段中断
• 对比 response_time_ms 是否异常短 → 判断是网络问题还是应用问题

{
  "stream_mode": true,
  "stream_chunks_received": 5,
  "stream_error_occurred": true,
  "error_message": "connection closed unexpectedly",
  "response_time_ms": 2100
}

官方 API vs 第三方平台的日志适配

如果你同时使用 Anthropic 官方 API 和第三方中转平台，需要适配日志字段。

字段	Anthropic 官方	第三方平台	适配策略
request_id	HTTP Header x-request-id 必有	可能无，或在响应 JSON 中	优先从 Header 获取，无则从 JSON 读取
error_type	标准值（如 invalid_request_error）	可能是非标准值	遇到未知值时，记录原值并标记为 unknown_error_type
endpoint	https://api.anthropic.com/v1/messages	如 https://api.newapi.com/v1/messages	记录完整 URL，便于区分来源
http_status_code	遵循 HTTP 标准	某些平台可能包装错误码	记录真实 HTTP 状态码

适配示例：

def extract_request_id(response, error_response):
    """兼容官方 API 和第三方平台的 request_id 提取"""
    # 优先从 Header 获取（官方 API）
    if hasattr(response, 'headers') and 'x-request-id' in response.headers:
        return response.headers['x-request-id']
    
    # 备选：从错误响应 JSON 中获取（第三方平台）
    if isinstance(error_response, dict) and 'request_id' in error_response:
        return error_response['request_id']
    
    # 都无则返回 "unknown"
    return "unknown"

日志设计检查清单

在部署日志系统前，用这份清单快速验证：

• 所有 API 调用失败都能被捕获并记录
• 必需字段（10 个）全部包含
• request_id 与 trace_id 都被正确记录
• API Key、messages 完整内容等敏感数据都已脱敏
• 日志格式是结构化 JSON，便于聚合分析
• 错误类型能覆盖 4xx / 5xx / timeout / stream_interrupted 等主要场景
• 流式和非流式调用的日志字段有区分
• 日志中包含足够的上下文（如 model、endpoint、SDK 版本）供诊断
• 已验证在 Python / TypeScript 等主要语言中的实现
• 配置了基于日志的监控告警规则

---

总结

一次失败的 Claude API 调用，应该记录什么？答案是：必需的 10 个字段（时间戳、trace_id、request_id、HTTP 状态码、错误类型、错误信息、模型、endpoint、SDK 版本、运行时），加上按需选择的推荐和可选字段。

从设计这个日志规范的那一刻起，你已经为未来的问题排查预留了通道。当问题真正发生时，一眼扫过结构化日志就能准确诊断，而不是在信息黑洞中摸索。这就是事前防守比事后诊断高效 10 倍的原因。

立即检查你的系统日志设计，对照本文的字段清单完善它——这个投入，会在第一次紧急故障排查时就回本。