Claude API 错误
Claude API 错误实用参考：响应格式、HTTP 状态码、常见原因以及安全重试规则。
更新于：2026 年 7 月 25 日。
错误格式
Claude API Tech 可以返回 Anthropic 或 OpenAI 兼容格式的错误。两种格式的 error 对象都包含错误类型和说明；Anthropic 格式中的 request_id 可帮助在调试或联系支持时定位具体请求。
Anthropic Error Format
JSON
{
"type": "error",
"error": {
"type": "rate_limit_error",
"message": "Rate limit exceeded"
},
"request_id": "req_..."
}OpenAI Error Format
JSON
{
"error": {
"message": "Invalid model ID",
"type": "invalid_request_error",
"code": "invalid_model"
}
}常见 HTTP 错误
| HTTP | 类型 | 含义 |
|---|---|---|
| 400 | invalid_request_error | JSON 无效、缺少必填字段、模型不支持某参数，或 messages 结构错误。 |
| 401 | authentication_error | API 密钥缺失、格式错误、已撤销或已过期。 |
| 403 | permission_error | 密钥有效，但无权访问模型、workspace 或其他资源。 |
| 404 | not_found_error | Endpoint、模型或资源 ID 不存在。 |
| 409 | conflict_error | 请求与资源当前状态冲突，例如资源被并发修改。 |
| 413 | request_too_large | HTTP 请求体过大。Anthropic 对 Messages 和 Token Counting API 的限制为 32 MB。 |
| 429 | rate_limit_error | 超出请求数、输入 token 或输出 token 限制；流量突然增长也可能触发加速限制。 |
| 500 | api_error | API 发生意外的内部错误。 |
| 504 | timeout_error | API 未能及时完成请求。 |
| 529 | overloaded_error | API 因整体流量暂时过载。 |
安全重试规则
仅重试临时错误，并逐次增加尝试之间的等待时间。
- 1遇到 429、500、504 和 529 时可以重试；其他 4xx 错误应先修正请求。
- 2服务器返回 retry-after 请求头时，始终遵守其中的等待时间。
- 3没有 retry-after 时，使用带随机 jitter 和最大延迟限制的指数退避。
- 4限制尝试次数，保留 request_id，不要盲目重试非幂等操作。
const RETRYABLE = new Set([429, 500, 504, 529]); async function requestWithRetry(url: string, init: RequestInit) { for (let attempt = 0; attempt < 5; attempt++) { const response = await fetch(url, init); if (response.ok) return response; if (!RETRYABLE.has(response.status) || attempt === 4) { throw new Error(`Request failed: ${response.status}`); } const retryAfter = response.headers.get("retry-after"); const retryAfterSeconds = Number(retryAfter); const backoff = Math.min(500 * 2 ** attempt, 10_000); const delay = retryAfter !== null && Number.isFinite(retryAfterSeconds) ? retryAfterSeconds * 1000 : backoff + Math.random() * 250; await new Promise((resolve) => setTimeout(resolve, delay)); }}