Claude API 报错:每个错误码是什么意思、怎么解决
更新于 2026-11-19
模型页:Claude Sonnet 5.5 API —— 价格、规格与在线体验
Claude API 的每个报错都是一段 JSON,里面有一个带 type 和 message 的 error 对象,外加一个请求 id。看 type 比看状态码更有用:同样是 500,可能是 api_error,也可能是 timeout_error;同样是 429,可能是每分钟限额、突然放量触发的限额,也可能是月度花费上限。Anthropic 还提醒 type 的取值以后可能增加,代码里要能处理没见过的类型。
这一页是总览。大家搜得最多的四个报错各有一页详细解法:529 过载、500、Claude Code 的 stream idle timeout、rate limit reached。下面的说法都来自 Anthropic 的 API 错误文档和 Claude Code 错误文档,核对日期 2026 年 11 月 19 日。
所有 Claude API 错误码一览
| 状态码 | error.type | 是什么意思 | 要不要重试 |
|---|---|---|---|
| 400 | invalid_request_error | 请求格式或内容有问题;你自己设的花费上限到了,也回这个。 | 不要,先改请求 |
| 401 | authentication_error | API key 格式不对、被吊销或过期。 | 不要,先换 key |
| 402 | billing_error | 账单或付款信息有问题。 | 不要 |
| 403 | permission_error | 这个 key 没有权限用这个资源。 | 不要 |
| 404 | not_found_error | 接口路径或资源 id 写错了。 | 不要 |
| 409 | conflict_error | 请求和资源当前的状态冲突。 | 解决冲突后再试 |
| 413 | request_too_large | 请求超过字节上限(Messages API 是 128 MB)。 | 不要,减少内容 |
| 429 | rate_limit_error | 速率限制、突然放量触发的限额,或者月度花费上限。 | 要,按 retry-after 等;花费上限重试没用 |
| 500 | api_error | Anthropic 内部出了意外错误。 | 要,按退避重试 |
| 504 | timeout_error | 处理超时。长请求改用流式。 | 要,最好改流式 |
| 529 | overloaded_error | API 暂时过载,所有用户都会遇到。 | 要,按退避重试 |
Claude Code 里看到的报错原文
Claude Code 遇到临时故障会先按指数退避自动重试,最多 10 次,所以你看到报错时,重试已经用完了。如果失败发生在一段文字或一次工具调用已经完成之后,它不会再重发,因为那样可能把同一个工具执行两遍。
API Error: Repeated 529 Overloaded errors:Anthropic 过载了。这不是你的用量上限,也不占你的额度。等一等,或者用 /model 换个型号,因为容量是按型号分开算的。详见下面的 529 页。
API Error: 500 Internal server error:服务端故障,和你的提示词、账号无关。先看 status.claude.com,等一分钟再发。
API Error: Request rejected (429)(旧版本写的是「Rate limit reached」):撞上了你的 API key 或云项目的速率限制。先跑 /status;环境变量里残留的 ANTHROPIC_API_KEY 可能让你走的是一个低档 key,而不是你的订阅。
Stream idle timeout / The response stopped arriving:连接还开着,但数据不再到达,Claude Code 的看门狗把它断掉了。
API Error: 400 due to tool use concurrency issues:历史里 tool_use、tool_result 和 thinking 块的顺序对不上了。先 claude update,再 /rewind 或连按两下 Esc。
Please run /login · API Error: 401:凭证被拒。先跑 /status;已生效的 ANTHROPIC_API_KEY 会优先于你的登录;如果用 ANTHROPIC_BASE_URL 走了网关,401 后面那段话是网关返回的。
先回 200、中途才报错的情况
用流式的时候,报错可能在 API 已经回了 200 之后才出现:流里会来一个名为 error 的事件,比如本来在非流式下会是 529 的 overloaded_error。只看状态码的代码接不住它,流里的 error 事件也要处理。
恢复的办法是:留住已经收到的那部分文字,再发一个请求让模型从断掉的地方接着写。Anthropic 说明,工具调用和 thinking 块没法只恢复一半,断在工具调用里的那一轮要整轮重做。
对大多数应用都适用的重试策略
先让 SDK 自己重试:官方 Python 和 TypeScript SDK 默认对连接错误、408、409、429 和 5xx 按指数退避重试两次,并遵守 retry-after。批量任务可以把 max_retries(TypeScript 里是 maxRetries)调大。
400、401、403、404、413 不要重试:同样的请求会以同样的方式失败。
没有 retry-after 的 429 要小心:套餐的月度花费上限不带 retry-after,下个月之前一直失败,重试只是浪费时间。
长请求用流式:Anthropic 建议可能超过 10 分钟的请求用流式或批处理,有些网络会在那之前就断掉空闲连接。
记下请求 id:每个响应都带 request-id 头,找客服时要用。
通过 APIMODELS 调用 Claude 有什么不同
在 APIMODELS 上,现役的每个 Claude 型号(Fable 5.2、Opus 5.5、Sonnet 5.5、Haiku 5.5)都至少有两条上游线路。第一条线路在开始回内容之前返回 429、5xx 或者连不上,请求会自动换到下一条,只有所有线路都失败了你才会看到报错,失败的请求不扣费。有一点我们也绕不过去:回答一旦开始流式返回,中途出的错没法再换线路,只能以流里的错误事件交给你。
长的流式回答:如果上游 30 秒内还没开始返回,我们先用 HTTP 200 把流打开,每 15 秒发一个 Anthropic 的 ping 事件,直到内容到达;之后流里一安静也会继续发 ping。这样代理和客户端的空闲计时器不会在模型长时间思考时把连接切断。代价是:这个 200 发出去之后,再出的错只能以流里的 error 事件到达,而不是 HTTP 状态码。我们自己的余额报错是 402 insufficient_credits,见下面的相关页面。
调用示例
cURL
curl https://api.apimodels.app/v1/messages \
-H "x-api-key: $APIMODELS_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-sonnet-5-5",
"max_tokens": 1024,
"stream": true,
"messages": [{"role": "user", "content": "Summarise this error log in three bullet points."}]
}'Python
import anthropic
# Same Anthropic SDK, pointed at APIMODELS. The SDK already retries 408/409/429/5xx
# with exponential backoff (twice by default); raise it for batch jobs.
client = anthropic.Anthropic(
base_url="https://api.apimodels.app",
api_key="sk_...your_apimodels_key...",
max_retries=4,
timeout=600,
)
try:
with client.messages.stream(
model="claude-sonnet-5-5",
max_tokens=1024,
messages=[{"role": "user", "content": "Summarise this error log in three bullet points."}],
) as stream:
for text in stream.text_stream:
print(text, end="", flush=True)
except anthropic.APIStatusError as e:
# e.status_code: 429 / 500 / 529 ...; the body carries error.type and a request id
print("failed:", e.status_code, e.response.headers.get("request-id"), e.message)常见问题
Claude Code 报 API Error 怎么解决?
先看「API Error」后面的状态码。529 和 500 是 Anthropic 那边的问题,等一分钟或用 /model 换个型号;429 是速率或花费上限,跑 /status,检查是否残留了 ANTHROPIC_API_KEY;400 的工具调用错误先 claude update 再 /rewind;401 是凭证被拒,跑 /status 和 /login。
哪些 Claude API 报错应该重试?
429(按 retry-after 等)、500、504 和 529 可以按指数退避重试,官方 SDK 默认已经会重试两次。400、401、403、404、413 不要重试,同样的请求还会失败。由月度花费上限引起的 429 不带 retry-after,上限重置之前重试都没用。
Claude 显示 overloaded 是什么意思?
就是 HTTP 529 overloaded_error:所有用户的访问量太大,Anthropic 的 API 暂时过载了。这不是你的速率限制,在 Claude Code 里也不占你的额度。等一会儿按退避重试,或者换一个 Claude 型号,因为容量是按型号分开算的。
为什么回答已经开始了还会报错?
用流式时,API 可能先回 200,再在流里发一个 error 事件,比如回答到一半来了个 overloaded_error。要处理流里的 error 事件,留住已收到的文字,再发一个请求让模型接着写。工具调用和 thinking 块没法只恢复一半,要整轮重做。
在 APIMODELS 上,失败的请求要扣钱吗?
不扣。在 APIMODELS 上失败的请求不收费。现役 Claude 型号都至少有两条上游线路,第一条线路在开始返回之前报错,会自动换下一条重试,只有所有线路都失败你才会看到报错。
