error-codes

# HTTP 错误代码参考 本文档记录了 Claude API 返回的 HTTP 错误代码、常见原因以及处理方法。有关特定语言的错误处理示例，请参阅 `python/` 或 `typescript/` 文件夹。 ## 错误代码摘要 | 代码 | 错误类型 | 可重试 | 常见原因 | | ---- | ----------------------- | --------- | ------------------------------------ | | 400 | `invalid_request_error` | 否 | 请求格式或参数无效 | | 401 | `authentication_error` | 否 | API 密钥无效或缺失 | | 403 | `permission_error` | 否 | API 密钥缺乏权限 | | 404 | `not_found_error` | 否 | 端点或模型 ID 无效 | | 413 | `request_too_large` | 否 | 请求超过大小限制 | | 429 | `rate_limit_error` | 是 | 请求过多 | | 500 | `api_error` | 是 | Anthropic 服务问题 | | 529 | `overloaded_error` | 是 | API 暂时过载 | ## 详细错误信息 ### 400 错误请求 **原因：** - 请求体中 JSON 格式错误 - 缺少必需参数 (`model`, `max_tokens`, `messages`) - 参数类型无效（例如：期望整数时传入了字符串） - 消息数组为空 - 消息未按用户/助手角色交替 **错误示例：** { "type": "error", "error": { "type": "invalid_request_error", "message": "messages: roles must alternate between "user" and "assistant"" }, "request_id": "req_011CSHoEeqs5C35K2UUqR7Fy" } **修复：** 在发送前验证请求结构。检查： - `model` 是否为有效的模型 ID - `max_tokens` 是否为正整数 - `messages` 数组是否非空且交替正确 --- ### 401 未授权 **原因：** - 缺少 `x-api-key` 或 `Authorization` 请求头 - API 密钥格式无效 - API 密钥已被撤销或删除 **修复：** 确保正确设置了 `ANTHROPIC_API_KEY` 环境变量。 --- ### 403 禁止访问 **原因：** - API 密钥无权访问请求的模型 - 组织级限制 - 在没有 Beta 访问权限的情况下尝试访问 Beta 功能 **修复：** 在控制台中检查您的 API 密钥权限。您可能需要不同的 API 密钥或申请特定功能的访问权限。 --- ### 404 未找到 **原因：** - 模型 ID 拼写错误（例如：`claude-sonnet-4.6` 应为 `claude-sonnet-4-6`） - U