参考数据：HTTP 错误码参考

Data: HTTP error codes reference

v2.1.63

Reference for HTTP error codes returned by the Claude API with common causes and handling strategies

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）
参数类型无效（例如，预期为整数却提供了字符串）
messages 数组为空
messages 未在 user/assistant 之间交替

错误示例：

json

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "messages: roles must alternate between \"user\" and \"assistant\""
  }
}

修复方法： 发送前验证请求结构。检查：

model 是否为有效的模型 ID
max_tokens 是否为正整数
messages 数组非空且正确交替

401 未授权

原因：

缺少 x-api-key 或 Authorization 请求头
API 密钥格式无效
API 密钥已被撤销或删除

修复方法： 确保正确设置了 ANTHROPIC_API_KEY 环境变量。

403 禁止访问

原因：

API 密钥无权访问请求的模型
组织级别的限制
尝试访问未授权的 beta 功能

修复方法： 在控制台中检查 API 密钥权限。可能需要使用不同的 API 密钥或申请特定功能的访问权限。

404 未找到

原因：

模型 ID 拼写错误（例如，claude-sonnet-4.6 应为 claude-sonnet-4-6）
使用了已弃用的模型 ID
API 端点无效

修复方法： 使用模型文档中的确切模型 ID。可以使用别名（例如 {\{OPUS_ID}\}）。

413 请求过大

原因：

请求正文超出最大大小限制
输入 token 过多
图像数据过大

修复方法： 减少输入大小——截断对话历史、压缩/调整图像大小或将大型文档拆分为多个块。

400 验证错误

部分 400 错误专门与参数验证相关：

max_tokens 超出模型限制
temperature 值无效（必须在 0.0-1.0 之间）
扩展思考中 budget_tokens >= max_tokens
tool 定义模式无效

扩展思考的常见错误：

# 错误：budget_tokens 必须小于 max_tokens
thinking: budget_tokens=10000, max_tokens=1000  → 错误！

# 正确
thinking: budget_tokens=10000, max_tokens=16000

429 速率限制

原因：

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

需要检查的请求头：

retry-after：重试前需等待的秒数
x-ratelimit-limit-*：您的限制
x-ratelimit-remaining-*：剩余配额

修复方法： Anthropic SDK 会自动使用指数退避重试 429 和 5xx 错误（默认：max_retries=2）。如需自定义重试行为，请参阅特定语言的错误处理示例。

500 内部服务器错误

原因：

Anthropic 服务临时问题
API 处理中的 bug

修复方法： 使用指数退避重试。如果问题持续存在，请查看 status.anthropic.com。

529 过载

原因：

API 需求过高
服务容量已达上限

修复方法： 使用指数退避重试。考虑使用不同的模型（Haiku 通常负载较低）、将请求分散到不同时间或实现请求队列。

常见错误及修复方法

错误	错误代码	修复方法
`budget_tokens` >= `max_tokens`	400	确保 `budget_tokens` < `max_tokens`
模型 ID 拼写错误	404	使用有效的模型 ID，如 `{\{OPUS_ID}\}`
第一条消息为 `assistant`	400	第一条消息必须为 `user`
连续出现相同角色的消息	400	在 `user` 和 `assistant` 之间交替
代码中硬编码 API 密钥	401	使用环境变量
需要自定义重试逻辑	429/5xx	SDK 自动重试；可通过 `max_retries` 自定义

SDK 中的类型化异常

始终使用 SDK 的类型化异常类，而不是通过字符串匹配检查错误消息。每个 HTTP 错误代码都映射到特定的异常类：

HTTP 代码	TypeScript 类	Python 类
400	`Anthropic.BadRequestError`	`anthropic.BadRequestError`
401	`Anthropic.AuthenticationError`	`anthropic.AuthenticationError`
403	`Anthropic.PermissionDeniedError`	`anthropic.PermissionDeniedError`
404	`Anthropic.NotFoundError`	`anthropic.NotFoundError`
429	`Anthropic.RateLimitError`	`anthropic.RateLimitError`
500+	`Anthropic.InternalServerError`	`anthropic.InternalServerError`
任何	`Anthropic.APIError`	`anthropic.APIError`

typescript

// ✅ 正确：使用类型化异常
try {
  const response = await client.messages.create({...});
} catch (error) {
  if (error instanceof Anthropic.RateLimitError) {
    // 处理速率限制
  } else if (error instanceof Anthropic.APIError) {
    console.error(`API 错误 ${error.status}:`, error.message);
  }
}

// ❌ 错误：不要通过字符串匹配检查错误消息
try {
  const response = await client.messages.create({...});
} catch (error) {
  const msg = error instanceof Error ? error.message : String(error);
  if (msg.includes("429") || msg.includes("rate_limit")) { ... }
}

所有异常类都继承自 Anthropic.APIError，该类具有 status 属性。使用 instanceof 检查时，应从最具体到最不具体（例如，先检查 RateLimitError，再检查 APIError）。

英文原文 / English Original

HTTP Error Codes Reference

This file documents HTTP error codes returned by the Claude API, their common causes, and how to handle them. For language-specific error handling examples, see the python/ or typescript/ folders.

Error Code Summary

Code	Error Type	Retryable	Common Cause
400	`invalid_request_error`	No	Invalid request format or parameters
401	`authentication_error`	No	Invalid or missing API key
403	`permission_error`	No	API key lacks permission
404	`not_found_error`	No	Invalid endpoint or model ID
413	`request_too_large`	No	Request exceeds size limits
429	`rate_limit_error`	Yes	Too many requests
500	`api_error`	Yes	Anthropic service issue
529	`overloaded_error`	Yes	API is temporarily overloaded

Detailed Error Information

400 Bad Request

Causes:

Malformed JSON in request body
Missing required parameters (model, max_tokens, messages)
Invalid parameter types (e.g., string where integer expected)
Empty messages array
Messages not alternating user/assistant

Example error:

json

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "messages: roles must alternate between \"user\" and \"assistant\""
  }
}

Fix: Validate request structure before sending. Check that:

model is a valid model ID
max_tokens is a positive integer
messages array is non-empty and alternates correctly

401 Unauthorized

Causes:

Missing x-api-key header or Authorization header
Invalid API key format
Revoked or deleted API key

Fix: Ensure ANTHROPIC_API_KEY environment variable is set correctly.

403 Forbidden

Causes:

API key doesn't have access to the requested model
Organization-level restrictions
Attempting to access beta features without beta access

Fix: Check your API key permissions in the Console. You may need a different API key or to request access to specific features.

404 Not Found

Causes:

Typo in model ID (e.g., claude-sonnet-4.6 instead of claude-sonnet-4-6)
Using deprecated model ID
Invalid API endpoint

Fix: Use exact model IDs from the models documentation. You can use aliases (e.g., {\{OPUS_ID}\}).

413 Request Too Large

Causes:

Request body exceeds maximum size
Too many tokens in input
Image data too large

Fix: Reduce input size — truncate conversation history, compress/resize images, or split large documents into chunks.

400 Validation Errors

Some 400 errors are specifically related to parameter validation:

max_tokens exceeds model's limit
Invalid temperature value (must be 0.0-1.0)
budget_tokens >= max_tokens in extended thinking
Invalid tool definition schema

Common mistake with extended thinking:

# Wrong: budget_tokens must be < max_tokens
thinking: budget_tokens=10000, max_tokens=1000  → Error!

# Correct
thinking: budget_tokens=10000, max_tokens=16000

429 Rate Limited

Causes:

Exceeded requests per minute (RPM)
Exceeded tokens per minute (TPM)
Exceeded tokens per day (TPD)

Headers to check:

retry-after: Seconds to wait before retrying
x-ratelimit-limit-*: Your limits
x-ratelimit-remaining-*: Remaining quota

Fix: The Anthropic SDKs automatically retry 429 and 5xx errors with exponential backoff (default: max_retries=2). For custom retry behavior, see the language-specific error handling examples.

500 Internal Server Error

Causes:

Temporary Anthropic service issue
Bug in API processing

Fix: Retry with exponential backoff. If persistent, check status.anthropic.com.

529 Overloaded

Causes:

High API demand
Service capacity reached

Fix: Retry with exponential backoff. Consider using a different model (Haiku is often less loaded), spreading requests over time, or implementing request queuing.

Common Mistakes and Fixes

Mistake	Error	Fix
`budget_tokens` >= `max_tokens`	400	Ensure `budget_tokens` < `max_tokens`
Typo in model ID	404	Use valid model ID like `{\{OPUS_ID}\}`
First message is `assistant`	400	First message must be `user`
Consecutive same-role messages	400	Alternate `user` and `assistant`
API key in code	401 (leaked key)	Use environment variable
Custom retry needs	429/5xx	SDK retries automatically; customize with `max_retries`

Typed Exceptions in SDKs

Always use the SDK's typed exception classes instead of checking error messages with string matching. Each HTTP error code maps to a specific exception class:

HTTP Code	TypeScript Class	Python Class
400	`Anthropic.BadRequestError`	`anthropic.BadRequestError`
401	`Anthropic.AuthenticationError`	`anthropic.AuthenticationError`
403	`Anthropic.PermissionDeniedError`	`anthropic.PermissionDeniedError`
404	`Anthropic.NotFoundError`	`anthropic.NotFoundError`
429	`Anthropic.RateLimitError`	`anthropic.RateLimitError`
500+	`Anthropic.InternalServerError`	`anthropic.InternalServerError`
Any	`Anthropic.APIError`	`anthropic.APIError`

typescript

// ✅ Correct: use typed exceptions
try {
  const response = await client.messages.create({...});
} catch (error) {
  if (error instanceof Anthropic.RateLimitError) {
    // Handle rate limiting
  } else if (error instanceof Anthropic.APIError) {
    console.error(`API error ${error.status}:`, error.message);
  }
}

// ❌ Wrong: don't check error messages with string matching
try {
  const response = await client.messages.create({...});
} catch (error) {
  const msg = error instanceof Error ? error.message : String(error);
  if (msg.includes("429") || msg.includes("rate_limit")) { ... }
}

All exception classes extend Anthropic.APIError, which has a status property. Use instanceof checks from most specific to least specific (e.g., check RateLimitError before APIError).

参考数据：HTTP 错误码参考 ​

HTTP 错误代码参考 ​

错误代码摘要 ​

详细错误信息 ​

400 错误请求 ​

401 未授权 ​

403 禁止访问 ​

404 未找到 ​

413 请求过大 ​

400 验证错误 ​

429 速率限制 ​

500 内部服务器错误 ​

529 过载 ​

常见错误及修复方法 ​

SDK 中的类型化异常 ​

HTTP Error Codes Reference ​

Error Code Summary ​

Detailed Error Information ​

400 Bad Request ​

401 Unauthorized ​

403 Forbidden ​

404 Not Found ​

413 Request Too Large ​

400 Validation Errors ​

429 Rate Limited ​

500 Internal Server Error ​

529 Overloaded ​

Common Mistakes and Fixes ​

Typed Exceptions in SDKs ​

参考数据：HTTP 错误码参考

HTTP 错误代码参考

错误代码摘要

详细错误信息

400 错误请求

401 未授权

403 禁止访问

404 未找到

413 请求过大

400 验证错误

429 速率限制

500 内部服务器错误

529 过载

常见错误及修复方法

SDK 中的类型化异常

HTTP Error Codes Reference

Error Code Summary

Detailed Error Information

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

413 Request Too Large

400 Validation Errors

429 Rate Limited

500 Internal Server Error

529 Overloaded

Common Mistakes and Fixes

Typed Exceptions in SDKs