Claude API 报错 429 怎么办？

429 是 rate_limit_error，说明你的请求频率超过了当前账户 Tier 的限额（RPM/TPM）。短期方案：加指数退避重试，起步等 1 秒，每次翻倍。长期方案：在 Anthropic Console 申请升 Tier，或者通过 API 聚合平台绕过单账户限流。

Claude 529 overloaded 和 429 有什么区别？

429 是你自己的问题——请求太多，超过了你账户的配额。529 是 Anthropic 那边的问题——服务器整体过载，所有用户都受影响。处理策略不同：429 需要降低请求频率或升级 Tier；529 只需要等几分钟重试，通常 2-5 分钟恢复。

Claude API 401 错误怎么排查？

401 authentication_error 三个常见原因：API Key 拼错或多了空格、Key 已过期或被吊销、用错了协议头（Anthropic 用 x-api-key，OpenAI 兼容协议用 Bearer token）。先在 Console 确认 Key 状态，再检查代码里的 Header 格式。

Claude API 超时怎么处理？

超时通常发生在长输出场景（max_tokens 设得很大）。建议开启 streaming 模式避免连接被中间网络设备断开，或者用 Message Batches API 处理超过 10 分钟的请求。国内用户还要考虑网络延迟，通过聚合平台的国内节点可以减少 200-400ms。

Claude API 报错信息里的 request_id 有什么用？

每个 API 响应都带 request-id 头，格式类似 req_018EeWyXxfu5pfWkrYcMdjWG。遇到无法自行解决的错误时，把这个 ID 发给 Anthropic 客服可以快速定位问题。Python SDK 通过 message._request_id 获取，TypeScript SDK 通过 message._request_id 获取。

Apr 4, 2026

claudeerror-handlingapi-guidetroubleshooting

Claude API 报错汇总：429/401/529/超时/overloaded 排查手册（2026）

调 Claude API 调到一半突然蹦出个 429，或者跑着跑着 529 overloaded。你去搜解决方案，发现有人说等一等就好，有人说要升 Tier，还有人说换个模型——到底哪个对？

问题在于 Claude 的报错分好几种，每种的成因和处理方式完全不同，搞混了只会越修越乱。这篇按错误码逐个说清楚，直连 Anthropic 官方还是走聚合平台都适用。

Claude API 错误码速查表

遇到报错直接按状态码查这张表：

状态码	错误类型	一句话解释	该怎么做
400	invalid_request_error	请求格式有问题	检查参数、模型名、JSON 格式
401	authentication_error	API Key 不对	确认 Key 有效、Header 格式正确
402	billing_error	账单或余额问题	检查付款方式和余额
403	permission_error	Key 没权限	确认 Key 的权限范围
404	not_found_error	资源不存在	检查 URL 和模型名拼写
413	request_too_large	请求体超限	Messages API 上限 32MB
429	rate_limit_error	请求频率超限	降频、退避重试、升 Tier
500	api_error	Anthropic 内部故障	重试，持续报就等官方修
529	overloaded_error	服务过载	等 2-5 分钟重试

Anthropic 的错误响应统一是 JSON 格式，包含 type 和 message 两个字段：

{
  "type": "error",
  "error": {
    "type": "rate_limit_error",
    "message": "Number of request tokens has exceeded your per-model limit."
  },
  "request_id": "req_011CSHoEeqs5C35K2UUqR7Fy"
}

注意看 request_id 字段，后面排查时会用到。

429 rate_limit_error：最常见也最容易误判

429 是大家碰到最多的报错。直觉反应是”我又没调几次，怎么就限流了”。但 Claude API 的限流不只看请求次数。

三种限流维度

Anthropic 同时检查三个指标，任何一个超了都会触发 429：

RPM（Requests Per Minute）：每分钟请求数
ITPM（Input Tokens Per Minute）：每分钟输入 token 数
OTPM（Output Tokens Per Minute）：每分钟输出 token 数

很多人只关注 RPM，结果一个带长上下文的请求直接把 ITPM 打满了。比如你往 Claude 塞了 10 万 token 的代码让它 review，一个请求就可能用掉整分钟的输入配额。

Tier 等级决定配额

Anthropic 根据充值金额划分 Tier，每升一级配额翻几倍。刚注册的免费账户配额很低，充 $5 以上才能到 Tier 1，$40 以上到 Tier 2，往上还有 Tier 3 和 Tier 4。具体每个 Tier 对应多少 RPM/TPM，在 Console 的 Limits 页面能看到。

排查步骤

先确认 429 的 message 内容——它会告诉你超的是 RPM、ITPM 还是 OTPM
到 Anthropic Console 查看当前 Tier 和剩余配额
如果是 ITPM 超限，压缩 prompt 长度或分批发送
如果是 RPM 超限，加请求间隔或做队列排队

指数退避重试

遇到 429 不能立刻重发，会加剧限流。正确做法是指数退避：第一次等 1 秒，第二次等 2 秒，第三次等 4 秒。Anthropic 官方 SDK（Python 和 TypeScript）内置了自动重试，默认重试 2 次，不需要自己写。

加速限流：一个隐藏的坑

还有个很多人不知道的机制叫 acceleration limits。你的用量如果突然飙升（比如从每天 100 次暴增到 10000 次），即使没超过 Tier 配额，也会被 429。Anthropic 的逻辑是怕突发流量冲击系统，所以加量得慢慢来。

如果你经常碰到 429，最直接的解决方案是通过 API 聚合平台调用。聚合平台在后端做了多账户负载均衡，单个用户的请求被分散到多个 Anthropic 账户，等于配额天然更高。关于费用问题，参考《Claude API 付费指南》。

529 overloaded_error：Anthropic 那边炸了

529 是 Anthropic 自定义的状态码，标准 HTTP 规范里没这个。意思是服务端整体过载，跟你个人配额没关系，所有人都在被影响。

容易碰到 529 的时候：新模型刚发布那几天用户涌入、美国工作时间的流量高峰、Anthropic 在做扩容升级。

529 只能等，但等法有讲究：

起步等 4 秒（比 429 的 1 秒要长）
依然用指数退避，但上限可以设到 60 秒
如果持续超过 5 分钟都是 529，大概率是 Anthropic 在出故障，可以去 status.anthropic.com 看状态
生产环境建议配 fallback 策略：529 超过阈值自动切到备用模型

如果你在用 Claude 做 Tool Use 或 Agent，529 中断会打断多轮调用链。建议在 Agent 循环里加断点重试逻辑，不要因为一个 529 就让整个任务失败。

401 authentication_error：别急着重新生成 Key

401 就是认证没过。大多数人第一反应是”Key 是不是错了”，但实际上原因比这多。

症状	可能原因	修复方式
刚生成的 Key 就报 401	Key 首尾多了空格或换行符	重新复制，trim 处理
之前能用突然 401	Key 被吊销（泄露到 GitHub 等）	Console 重新生成
换了代码就 401	Header 格式不对	Anthropic 用 `x-api-key`，不是 `Authorization: Bearer`
通过聚合平台 401	聚合平台的 Key 和 Anthropic 的 Key 搞混	确认用的是哪个平台的 Key

Anthropic 原生 vs OpenAI 兼容协议

这是国内开发者最容易踩的坑。直连 Anthropic 用 x-api-key 头，通过 OpenAI 兼容协议（比如 ofox.ai 的 api.ofox.ai/v1）调用时用 Authorization: Bearer 头。Header 用错了就是 401，错误信息还不一定直接告诉你是 Header 的问题。

API Key 安全提醒

Anthropic 和 GitHub 有联动检测：你的 Key 如果出现在公开代码库里，会被自动吊销。吊销不会通知你，下次调用直接 401。建议所有 Key 放环境变量，代码里只引用变量名。

402 billing_error：付款出了问题

402 倒是很直白，就是钱没到位。

免费额度花完了没绑卡、信用卡过期扣款失败、或者账户已经欠费了，都会触发 402。

Anthropic 官方只支持国际信用卡，不接受支付宝和微信。很多国内开发者用虚拟信用卡绑定后，因为风控被拒付，账户进入 402 状态。这时候即使重新绑卡也可能需要等 Anthropic 人工审核。

绕过这个麻烦最简单的方式是通过聚合平台付费，支付宝微信直充，不存在信用卡被拒的问题。

400 invalid_request_error：你的请求写错了

400 是个筐，各种请求格式问题都往里装。挑几个 Claude 特有的高频坑：

模型名拼错

Claude 的模型 ID 命名有自己的规则，不是随便写的。当前（2026 年 4 月）主力模型 ID：

claude-opus-4-6（旗舰模型，详见《Claude Opus 4.6 完全指南》）
claude-sonnet-4-6（性价比首选）
claude-haiku-4-5-20251001（轻量快速）

写成 claude-4-opus 或 claude-opus-4.6（用点号而不是连字符）都会报 400。

Opus 4.6 不支持 prefill

Claude Opus 4.6 不允许预填充 assistant 消息。如果你习惯了在其他模型上用 prefill 控制输出格式，换到 Opus 4.6 会碰到这个 400：

Prefilling assistant messages is not supported for this model.

替代方案：用 system prompt 指定输出格式，或者用 structured outputs 功能。

请求体超限

Messages API 的请求体上限是 32MB。通常不会碰到，除非你在 messages 里塞了大量图片（vision 功能）。如果需要处理更大的输入，可以用 Files API（上限 500MB）先上传再引用。

“there’s an issue with the selected model”

这个错误信息在某些客户端（Cursor、Cherry Studio 等）会出现，本质是模型 ID 写错或者当前 API Key 没有该模型的访问权限。检查模型名拼写和 Key 的权限范围。

403 permission_error 和 404 not_found_error

不常见，但碰到了也别懵。

403：你的 API Key 没有访问某个资源的权限。比如你用一个只有 Messages API 权限的 Key 去调 Admin API，就会 403。

404：请求的资源不存在。最常见的是 URL 路径拼错，比如把 /v1/messages 写成 /v1/message（少了 s）。

超时和连接断开

超时不返回 HTTP 错误码，因为连接直接断了，响应根本收不到。Debug 的时候最烦这种——没有错误信息，只有一个 timeout exception。

为什么 Claude API 容易超时

Claude 处理长文本时（特别是开了 Extended Thinking 的 Opus 4.6），单次请求可能跑十几秒甚至几分钟。中间经过的任何网络设备（CDN、代理、防火墙）如果有空闲连接超时设置，就可能主动断开。

怎么解决

最有效的是开 streaming。数据持续在流动，中间的网络设备不会把连接判定为”空闲”然后砍掉。Anthropic 自己也建议超过 10 分钟的请求一律用 streaming。

不需要实时拿结果的场景，用 Message Batches API 更省心——异步提交，轮询取结果，连接断了也无所谓。

直接对接 API 的话，在 socket 层开 TCP keep-alive 能减少被中间设备踢掉的概率，官方 SDK 默认已经开了。国内用户还有个额外因素：跨境网络延迟高、丢包率高，走聚合平台的国内节点可以省掉 200-400ms。

Streaming 中途的错误

用 streaming 模式时，HTTP 状态码返回的是 200（因为连接已经建立了），然后错误通过 SSE 事件流里的 error event 返回。这意味着你不能只靠 HTTP 状态码判断成功，还要解析事件流里的错误事件。

官方 SDK 已经处理了这个情况。如果你自己实现 SSE 解析，记得监听 error 类型的事件。

request_id：排查报错的关键线索

每个 Claude API 响应都带一个 request-id 头，即使报错也有。格式是 req_ 开头的字符串。

这个 ID 的用处：

记到你的日志里，方便回溯
联系 Anthropic 客服时附上，对方能直接查到你那次请求的完整链路
如果同一个 request_id 出现在多次响应里，说明中间有重试（可能是 SDK 自动触发的）

SDK 获取方式：

Python：message._request_id
TypeScript：message._request_id

生产环境的错误处理建议

如果你的应用已经上线，或者在跑 AI Agent，错误处理不能只是 print 一行日志。

首先分清楚哪些错该重试、哪些不该。4xx 里除了 429 都不要重试，400 说明你请求写错了，重发一万次还是错。429 用指数退避，最多试 3-5 次。5xx 和 529 可以重试，但起步间隔拉长到 4 秒。超时的话，先通过 request_id 确认请求是不是已经在 Anthropic 那边执行了，免得重复计费。

生产环境别只挂一个模型。429 或 529 连续出现超过你设的阈值时，自动切到 GPT-5.4 或 Gemini 3.1 Pro。通过聚合平台调用的话，平台那边就能配 fallback 路由。跨模型的错误处理思路参考《AI API 报错排查完全指南》。

日志方面，每次 API 调用至少记下 request_id、模型名、输入输出 token 数、响应时间和状态码。出了问题翻日志就行，不用事后复现。

通过聚合平台降低报错率

很多报错本质上是”直连 Anthropic 官方 API 在国内水土不服”造成的：网络不稳导致超时、信用卡问题导致 402、单账户配额不够导致 429。

通过 ofox.ai 这类 API 聚合平台调用，几个高频问题可以一起解决。429 限流方面，聚合平台后端有多账户负载均衡，配额池比个人账户大得多。超时问题，国内直连节点延迟 200-500ms，比走国际线路稳定很多。付费那个 402 就更不用说了，支付宝微信直充，不用折腾信用卡。529 过载的话，部分平台还支持自动 fallback，Anthropic 那边扛不住时切到其他渠道。

接口协议完全兼容，改一行 base_url 就行。Claude API 国内接入的完整教程在这里。

回头看

Claude API 的报错分两边：4xx 是你这边的事（请求写错了、Key 有问题、配额不够），5xx 和 529 是 Anthropic 那边的事。遇到报错先看状态码和 error message 里的 type 字段，九成情况能直接定位。

429 最容易误判——不只是请求太频繁，输入 token 太多一样会触发。529 别慌，等几分钟就好。不管碰到什么报错，记得把 request_id 记下来，后面排查全靠它。