Claude API「Rate limit reached」429 是什么意思、怎么解决
更新于 2026-11-19
模型页:Claude Sonnet 5.5 API —— 价格、规格与在线体验
Anthropic 按型号类别分别限制每分钟请求数(RPM)、每分钟输入 token(ITPM)和每分钟输出 token(OTPM),用的是令牌桶:额度一直在慢慢补,不是整分钟清零。60 RPM 可能被按每秒 1 个请求来执行,所以短时间的突发请求即使每分钟平均没超,也会触发 429。只有没命中缓存的输入 token 才计入 ITPM,所以提示词缓存能直接提高你实际可用的额度。
Claude Code 里的提示文字改过几次。旧版本写的是「API Error: Rate limit reached」;现在的版本里,撞上你 key 的速率限制显示「API Error: Request rejected (429)」,Anthropic 那边的短暂限流显示「Server is temporarily limiting requests (not your usage limit)」,订阅额度用完显示「You've hit your session limit」。
几种 429,哪些会自己好
| 原因 | 怎么分辨 | 怎么办 |
|---|---|---|
| RPM / ITPM / OTPM 超了 | 报错里写明是哪项限额;带 retry-after | 等 retry-after 秒,再把请求摊平 |
| 突然放量触发 ramp 限额 | error.details.error_code 是 ramp_limit_exceeded | 等 retry-after,之后每分钟最多加一档流量 |
| 套餐月度花费上限 | error_code 是 enforced_spend_limit_reached;没有 retry-after | 下个月 1 号 UTC 0 点之前重试都失败;升到更高档 |
| 你自己设的花费上限 | 回的是 HTTP 400 invalid_request_error,不是 429(Claude Code 工作区的上限可能回 429) | 去控制台把自己设的上限调高 |
| Claude Code 订阅额度 | 「You've hit your session limit · resets ...」 | 等额度重置,或者改用按 token 计费的 API key |
怎么解决
1. 按 retry-after 来。 有这个头时,它就是要等的秒数,提前重试可能失败。官方 SDK 已经会遵守它。
2. 看 anthropic-ratelimit 系列响应头。 每个响应都会给出请求数和 token 的上限、剩余量和重置时间,撞墙之前就能先放慢。
3. 把突发摊平。 请求均匀发出,限制并发;Claude Code 里别一下子开很多并行子代理。
4. 用提示词缓存。 命中缓存的输入 token 不计入 ITPM,很长的公共 system 提示词或代码库上下文缓存之后,占用的额度会少很多。
5. 慢慢加量。 定时任务和批量任务从低速开始,一档一档往上加;Message Batches API 不受 ramp 限额约束。
6. Claude Code 里跑 /status。 环境变量里残留的 ANTHROPIC_API_KEY 可能让请求走一个低档 key,而不是你的订阅。
通过 APIMODELS 调用 Claude 时的限流
在 APIMODELS 上你没有 Anthropic 组织,所以 Anthropic 的用量档位和套餐月度花费上限管不到你;你按 token 从余额里付费,余额用完回的是我们自己的 402 insufficient_credits,而不是 429。上游的速率限制依然存在,这时候多条线路就起作用了。
在 APIMODELS 上,现役的每个 Claude 型号(Fable 5.2、Opus 5.5、Sonnet 5.5、Haiku 5.5)都至少有两条上游线路。第一条线路在开始回内容之前返回 429、5xx 或者连不上,请求会自动换到下一条,只有所有线路都失败了你才会看到报错,失败的请求不扣费。有一点我们也绕不过去:回答一旦开始流式返回,中途出的错没法再换线路,只能以流里的错误事件交给你。
调用示例
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 显示「Rate limit reached」是什么意思?
就是 429 rate_limit_error:每分钟请求数、输入 token 或输出 token 超了,请求量涨得太猛,或者撞上了花费上限。新版 Claude Code 对同一种情况显示「API Error: Request rejected (429)」。按 retry-after 等一等,再把请求摊平。
Claude 429 之后要等多久?
有 retry-after 头就等它给的秒数,提前重试可能失败。如果没有 retry-after、error_code 是 enforced_spend_limit_reached,说明撞上了套餐的花费上限,下个月 1 号 UTC 0 点之前请求都会失败。
明明没超限额,为什么还报 429?
常见两个原因。Anthropic 用令牌桶执行限额,60 RPM 可能相当于每秒 1 个请求,短时间的突发就会触发;另外请求量突然大涨之后,即使没超 ITPM 和 OTPM,也可能因为 ramp 限额(ramp_limit_exceeded)回 429,要一档一档慢慢加量。
Claude Code 里的「rate limited」是什么意思?
意思是 Claude Code 正在用的 API key、Bedrock 项目或 Google Cloud 项目撞上了它配置的速率限制。跑 /status 看看当前生效的是哪个凭证,残留的 ANTHROPIC_API_KEY 会盖过你的订阅;同时减少并行子代理。「Server is temporarily limiting requests」是 Anthropic 那边的短暂限流,不是你的额度。
在 APIMODELS 上也有 Anthropic 的用量档位限制吗?
没有。在 APIMODELS 上你不是 Anthropic 的组织,它的用量档位和套餐月度花费上限管不到你,你按 token 从余额付费。上游的速率限制仍然存在,但现役 Claude 型号都至少有两条上游线路,回答开始前的 429 会自动换下一条重试。
