Claude API 报错怎么办？2026 Claude API 错误码大全（400、401、429、529 解决方法）

Claude API 报错时，先看 HTTP 状态码：4xx 大多是请求本身的问题，改请求才能解决，重试没用；429、500、529 这类才是可以等一等再重试的临时错误。分清这一点，大部分 Claude API 错误几分钟就能定位。

这篇 Claude API 错误码大全按状态码逐一说明含义、常见原因和解决方法，再汇总新一代模型特有的 400 报错，最后给出 Python 重试代码和 Claude Code 的排查清单。还没跑通第一次调用的话，先看《Claude API 调用教程：Python 接入 Claude API 完整示例》。

---

Claude API 错误码速查表

状态码	错误类型	能否重试	含义
400	invalid_request_error	否	请求格式或参数有问题
401	authentication_error	否	API Key 无效、已撤销或已过期
402	billing_error	否	账单或支付信息有问题
403	permission_error	否	当前 Key 没有权限访问该资源
404	not_found_error	否	接口路径错误，或模型不存在 / 不可用
413	request_too_large	否	请求体超过大小限制
429	rate_limit_error	是	触发速率限制或消费上限
500	api_error	是	Anthropic 内部错误
504	timeout_error	视情况	请求处理超时
529	overloaded_error	是	API 暂时过载

所有错误都以 JSON 返回，结构如下：

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

error.message 通常已经写明了原因，request_id 在联系技术支持时一定要带上。

---

Claude API 4xx 报错：需要修改请求

400 invalid_request_error

最常见的 Claude API 报错，原因包括：

• JSON 格式错误，或缺少 model、max_tokens、messages 等必填参数；
• messages 为空、第一条不是 user，或 user / assistant 没有交替出现；
• max_tokens 超过了模型上限；
• 传入了不存在或未开通的 anthropic-beta 值；
• 组织或工作区达到了你自己设置的消费上限。

解决方法：按 error.message 的提示修改请求。同一个有问题的请求，重试多少次结果都一样。

401 authentication_error

API Key 格式错误、已撤销或已过期，或请求头里缺少 Key。用中转站时，最常见的原因是把官方 Key 填到了中转站，或者复制 Key 时多了空格。同时设置了 ANTHROPIC_API_KEY 和 ANTHROPIC_AUTH_TOKEN 时，API Key 优先，旧 Key 失效也会导致 401，删掉不用的那个即可。

402 billing_error 与 403 permission_error

402 表示支付信息有问题或余额不足，到控制台检查账单。403 表示当前 Key 所在的组织或工作区不允许执行这个操作，或被地区限制等访问要求拦截，检查组织和工作区的权限设置。

404 not_found_error

• 模型 ID 拼错，例如把 claude-sonnet-5-5 写成 claude-sonnet-5.5；
• 使用了已退役的模型，或该模型对你的组织不可用；
• Base URL 或接口路径写错。

模型不存在和模型对你不可用，返回的是同一种 404。调用 GET /v1/models 可以查看当前 Key 能用哪些模型。Base URL 的填写规则见《Base URL 是什么？API Base URL 怎么填》。

413 request_too_large

请求体超过大小上限（Messages API 为 128 MB），常见于一次塞入过大的图片、PDF 或超长对话历史。压缩图片、拆分文档，或精简对话历史后再发送。

---

Claude API 429 报错：限速与消费上限

429 rate_limit_error 有两种完全不同的情况：

情况	特征	处理方法
速率限制	超过每分钟请求数（RPM）或 Token 数（TPM），响应头带 retry-after	等待 retry-after 指定的秒数后重试，降低并发
消费上限	达到用量等级的月度消费上限，没有 retry-after 头	重试无效，需要提高上限或升级用量等级

另外，组织用量突然暴增时，可能触发加速限制（acceleration limits）而收到 429。官方建议逐步增加流量，保持稳定的调用节奏。

用中转站时，429 也可能来自中转站自己的分组限速，可以在控制台查看 Key 的限额。在 Claude Code 中遇到 429 的处理方法，见《Claude Code Token 消耗太快？10 个 Claude Code 省 Token 技巧》。

---

Claude API 5xx 报错：服务端问题

500 api_error

Anthropic 内部出现了意外错误。用指数退避重试；持续出现时，带上 request_id 联系技术支持。

504 timeout_error

请求处理超时。生成长内容或 max_tokens 很大时，改用流式输出或 Message Batches API。官方 SDK 会检查非流式请求是否可能超过 10 分钟，超过时要求改用流式。

529 overloaded_error

API 暂时过载，通常和你自己的用量无关，也不代表你的额度出了问题。稍后重试即可，也可以临时切换到负载较低的模型。

---

新一代 Claude 模型特有的 400 报错

从旧模型迁移到 Opus 5.5、Sonnet 5.5 等新模型时，这些报错最常见：

报错信息（节选）	原因	解决方法
"thinking.type.disabled" is not supported for this model	Opus 5.5、Fable 5.1 的思考无法关闭	删掉 thinking 参数，用 output_config.effort 控制强度
"thinking.type.enabled" is not supported for this model	新模型已移除 budget_tokens 写法	改用 thinking: {"type": "adaptive"}
tool_choice: type "tool" and "any" are not supported	Opus 5.5、Sonnet 5.5、Fable 5.1 不支持强制工具调用	改用 tool_choice: {"type": "auto"}，在提示词里指明要用的工具
does not support assistant message prefill	Claude 4.6 及之后的模型不支持预填充	用结构化输出或系统提示控制格式
传入 temperature / top_p / top_k 报 400	新模型已移除这些采样参数	删除这些参数
thinking blocks ... cannot be modified	回传时修改、过滤了思考块	把助手消息里的思考块原样传回

Claude 各模型的区别见《Claude Opus 和 Sonnet 有什么区别？2026 Claude 模型对比与选型指南》。

---

用 Python 处理 Claude API 错误

官方 SDK 默认会对连接错误、429 和 5xx 自动重试 2 次，并遵守 retry-after 头。重试用完仍失败时，按错误类型分别处理：

import anthropic

client = anthropic.Anthropic(
    base_url="https://api.supastore.cc/v1",
    max_retries=4,  # 默认 2
)

try:
    message = client.messages.create(
        model="claude-sonnet-5-5",
        max_tokens=16000,
        messages=[{"role": "user", "content": "你好"}],
    )
    print(message._request_id)
except anthropic.BadRequestError as e:
    print("请求有误，需要修改参数：", e.message)
except anthropic.AuthenticationError:
    print("API Key 无效，检查 Key 和 base_url")
except anthropic.NotFoundError as e:
    print("模型或接口不存在：", e.message)
except anthropic.RateLimitError as e:
    print("触发限速，retry-after =", e.response.headers.get("retry-after"))
except anthropic.APIStatusError as e:
    print(f"请求失败 {e.status_code}，request_id =", e.request_id)
except anthropic.APIConnectionError:
    print("网络连接失败")

捕获时从最具体的异常类开始，不要用一个宽泛的异常吞掉所有错误，否则无法区分"该改代码"和"该等一等"。

---

Claude Code 报 API Error 怎么排查

Claude Code 里看到 API Error 时，按这个顺序检查：

1. 看状态码：401 查 Key，404 查 Base URL 和模型，429 降低并发，529 稍后重试；
2. 检查环境变量：运行 echo $ANTHROPIC_BASE_URL，确认地址和 Key 已生效；
3. 运行 claude doctor：检查安装和配置文件是否有错误；
4. 看用量：用 /usage 确认是否触及订阅或 Key 的额度上限；
5. 查中转站日志：通过中转站使用时，在控制台使用日志里查看请求详情。

中转站的完整配置和报错对照，见《Claude API 中转怎么用？国内 Claude Code 中转站配置教程》和常见问题排查。

---

常见问题 (FAQ)

Q: Claude API 报 529 overloaded_error 是什么意思？

答： 529 表示 Claude API 暂时过载，通常与你自己的用量无关，稍后重试即可；官方 SDK 会自动重试，也可以临时切换到负载较低的模型。

Q: Claude API 429 和 529 有什么区别？

答： 429 是你的组织超过了速率限制或消费上限，需要降低请求频率或调整额度；529 是 Claude API 整体负载过高，与你的额度无关，等待后重试即可。

Q: Claude API 400 错误可以重试吗？

答： 不可以，400 表示请求格式或参数有问题，重试只会得到同样的错误，需要按 error.message 的提示修改请求后再发送。

Q: Claude API 报 404 但模型名没写错怎么办？

答： 检查 Base URL 是否正确，以及该模型是否对你的 Key 开放；调用 GET /v1/models 可以查看当前 Key 能使用的模型列表。

Q: 联系技术支持需要提供什么信息？

答： 提供错误响应中的 request_id 或响应头里的 request-id，以及状态码、错误信息和请求时间，方便快速定位问题。