Claude API 错误码大全

调用 Claude API 时遇到错误？本文汇总了所有 Claude API 错误码，逐一解释原因并提供解决方案，帮你快速排查和解决问题。

错误响应格式

Claude API 的错误响应统一为以下 JSON 格式：

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "具体错误描述信息"
  }
}

400 Bad Request — 请求格式错误

错误类型：invalid_request_error

常见原因：

• 请求 JSON 格式不正确或缺少必填字段
• model 参数值不正确
• messages 数组为空或格式不对
• max_tokens 超出模型上限
• 图片格式不支持或 base64 编码错误

解决方案：

# 检查请求格式
request_body = {
    "model": "claude-sonnet-4-20250514",  # 确认模型名称正确
    "max_tokens": 1024,                    # 不超过模型上限
    "messages": [
        {
            "role": "user",               # 角色必须是 user 或 assistant
            "content": "Hello"             # 内容不能为空
        }
    ]
}

401 Unauthorized — 认证失败

错误类型：authentication_error

常见原因：

• API Key 缺失或格式错误
• API Key 已被吊销或过期
• 请求头中 x-api-key 或 Authorization 格式不正确

解决方案：

# 确保正确设置 API Key
import anthropic

# 方式一：直接传入
client = anthropic.Anthropic(api_key="sk-ant-xxxx")

# 方式二：环境变量（推荐）
# export ANTHROPIC_API_KEY="sk-ant-xxxx"
client = anthropic.Anthropic()

# 方式三：使用中转站 Key
client = anthropic.Anthropic(
    api_key="cr_xxxx",
    base_url="https://claude4u.com/v1"
)

403 Forbidden — 权限不足

错误类型：permission_error

常见原因：

• API Key 没有访问该模型的权限
• 账户所在地区不支持某些功能
• 组织级权限限制

解决方案：检查账户权限设置，确认 API Key 有权访问目标模型。如果是地区限制，可以通过中转服务访问。

404 Not Found — 资源不存在

错误类型：not_found_error

常见原因：

• API 端点路径错误（如 /v1/message 应为 /v1/messages）
• 模型名称拼写错误（如 claude-sonnet-4 应为 claude-sonnet-4-20250514）
• Batch ID 不存在

解决方案：

# 检查 API 端点
# 正确：POST https://api.anthropic.com/v1/messages
# 错误：POST https://api.anthropic.com/v1/chat/completions （这是 OpenAI 格式）

# 检查模型名称
# 正确的模型名：
models = [
    "claude-opus-4-20250514",
    "claude-sonnet-4-20250514",
    "claude-haiku-3-5-20241022"
]

429 Too Many Requests — 超出限流

错误类型：rate_limit_error

常见原因：

• 超出 RPM（每分钟请求数）限制
• 超出 TPM（每分钟 Token 数）限制
• 超出 TPD（每日 Token 数）限制

解决方案：

import time

def retry_on_rate_limit(func, max_retries=5):
    for attempt in range(max_retries):
        try:
            return func()
        except anthropic.RateLimitError as e:
            wait = min(2 ** attempt * 5, 60)
            print(f"Rate limited, retrying in {wait}s...")
            time.sleep(wait)
    raise Exception("Max retries exceeded")

500 Internal Server Error — 服务器内部错误

错误类型：api_error

常见原因：

• Anthropic 服务端临时故障
• 请求触发了服务端 Bug

解决方案：稍后重试即可。如持续出现，检查请求内容是否包含特殊字符或超大数据，尝试简化请求。

529 Overloaded — 服务过载

错误类型：overloaded_error

常见原因：

• Anthropic API 服务负载过高
• 热门模型在高峰时段容量不足

解决方案：

# 529 通常是暂时性的，建议等待后重试
import anthropic

try:
    response = client.messages.create(...)
except anthropic.APIStatusError as e:
    if e.status_code == 529:
        print("服务暂时过载，30秒后重试")
        time.sleep(30)
        # 重试请求

错误处理最佳实践

1. 区分可重试错误：429、500、529 可重试；400、401、403 需要修改请求
2. 使用指数退避：重试间隔逐步增大，避免雪崩
3. 记录错误日志：保存完整错误信息，便于排查
4. 设置超时：避免长时间等待无响应的请求
5. 熔断机制：连续失败超过阈值时暂停请求，保护系统