【Claude】Request rejected (429) 速率限制报错已解决

步入烟尘

597人浏览 · 2026-06-28 01:55:44

步入烟尘 · 2026-06-28 01:55:44 发布

【Claude】Request rejected (429) 速率限制报错已解决

关键词：Claude Code、429、rate limit、速率限制、RPM、TPM、TPD、ANTHROPIC_API_KEY、并发、指数退避

一、问题现象：请求被拒，429

API Error: Request rejected (429) · this may be a temporary capacity issue. If it persists, check https://status.claude.com.

如果你走的是 Bedrock / Vertex AI / Foundry 或自定义网关，状态页链接会指向对应提供商，而不是 status.claude.com。

关键词：429（HTTP 标准状态码，Too Many Requests）。

二、429 的本质：三层速率限制同时生效

2.1 HTTP 429 的标准含义

429 是 HTTP 标准状态码，含义是"请求过多（Too Many Requests）"——服务端告诉你，在一定时间窗口内，你的请求频率超过了允许的上限。

2.2 Claude API 的三层速率限制

Anthropic API 同时维护三个维度的速率限制，任何一个触碰都会返回 429：

维度	含义
RPM（Requests Per Minute）	每分钟请求次数上限
TPM（Tokens Per Minute）	每分钟 Token 吞吐量上限
TPD（Tokens Per Day）	每日 Token 总量上限

每个 API key 所属的 Tier（层级）决定了具体的限制数值。Anthropic 的 Tier 体系大致是：消费越多/账号越老 → Tier 越高 → 限制越宽松。

2.3 Claude Code 里 429 的触发路径

在 Claude Code 中，有几种典型触发场景：

流浪的低 Tier API key 覆盖了订阅：环境变量 ANTHROPIC_API_KEY 里藏着一个老的、低 Tier 的 key，而你其实有 Pro/Max 订阅——这是最常被忽视的坑；
并行子代理 / 工具调用并发过高：多个 Agent 同时请求，合并速率超过 key 的 RPM/TPM 上限；
Bedrock / Vertex AI 项目的速率配额不够：云提供商层面的限制，与 Anthropic 账户无关；
真实的速率触碰：脚本高速循环调用。

三、解决方案

方案一：检查当前活跃凭证（最重要，第一步必做）

这是最容易被跳过、却最关键的一步。运行：

/status

查看 Claude Code 实际使用的是哪个凭证。重点检查：

是不是一个 ANTHROPIC_API_KEY 环境变量里藏的低 Tier key 在起作用？

从同一个 shell 运行：

env | grep ANTHROPIC

如果 ANTHROPIC_API_KEY 有值，而你本意是用订阅（/login）来认证，这个 key 会优先于订阅凭证。取消设置：

unset ANTHROPIC_API_KEY

然后从 shell 配置文件（~/.zshrc、~/.bashrc、项目 .env）中彻底删掉它。再用 /status 确认凭证已切回订阅。

方案二：检查提供商控制台，查看活跃限制

如果你用的是 Anthropic API key（Console）：

登录 platform.claude.com，查看你的 key 所在的 Tier 和当前速率限制；
如果需要更高配额，通过 Console 申请提升 Tier；
可以在 Console 里为每个工作区设置支出上限（spending cap），防止单个项目把整个组织的配额耗尽。

如果你用的是 Bedrock / Vertex AI / Foundry：

进入对应云提供商的控制台，查看该项目的配额配置；
申请更高的并发或 TPM 限制。

方案三：降低并发与切换模型

调小工具调用并发：

export CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY=2

减少并行子代理：如果你在跑多 Agent 编排，减少同时运行的 Agent 数量。

切换到较小的模型：对于高容量脚本跑批任务，切到 Sonnet 或 Haiku，它们的速率限制通常比 Opus 更宽。

/model

方案四：在脚本里加指数退避重试

如果你自己写脚本直接调 API，必须实现退避重试，而不是朴素循环：

import time
import anthropic

client = anthropic.Anthropic()
delay = 5

for attempt in range(8):
    try:
        resp = client.messages.create(
            model="claude-sonnet-4-5",
            max_tokens=1024,
            messages=[{"role": "user", "content": "your prompt"}]
        )
        break
    except anthropic.RateLimitError:  # 429
        if attempt == 7:
            raise
        wait = delay * (2 ** attempt)  # 指数退避：5, 10, 20, 40...
        print(f"429 - 等待 {wait}s 后重试 (attempt {attempt+1}/8)")
        time.sleep(wait)

关键点：

要读 retry-after 响应头（如果有的话），按它的指定时间等待；
不要立即重试——立即重试 429 会触发更严重的限制；
退避上限封顶（比如最多等 60 秒），避免无限等待。

在 Claude Code CLI 里，这部分由 CLI 自己处理——CLAUDE_CODE_MAX_RETRIES 和 CLAUDE_CODE_RETRY_WATCHDOG 控制重试行为（详见官方文档中的自动重试章节）。

四、429 vs 其他相似错误

错误	码	核心区别
Request rejected (429)	429	你触发速率限制，检查凭证/降并发
`Server is temporarily limiting requests`	—	服务端全局限流，非你账户，等片刻
`Repeated 529 Overloaded`	529	模型容量满，换模型
`You've hit your session limit`	—	订阅配额耗尽，等重置或买 Extra

一个简单记忆：429 = 你的 key/账户被限；529 = 模型被挤爆；"Server is temporarily"= 服务端全局，和你无关。

五、避坑与最佳实践

❌ 不要立即无脑重试：429 重试不等待会雪上加霜；
❌ 不要忽视环境变量里的游荡 key：env | grep ANTHROPIC 先查一遍；
✅ 第一步永远是 /status：确认真正在使用的凭证；
✅ 脚本必须指数退避：5s → 10s → 20s → 40s…；
✅ 高并发任务调小 MAX_TOOL_USE_CONCURRENCY；
✅ 批量任务选小模型：Sonnet/Haiku 的速率上限通常更宽。

六、总结

Request rejected (429) 是你的 API 凭证 / 项目触发了速率限制。最关键的第一步：/status + env | grep ANTHROPIC，确认活跃凭证——很多时候一个游荡的低 Tier key 就是根因，取消设置后订阅凭证接管，立刻恢复。检查完凭证再看是否需要降并发、申请更高 Tier、或给脚本加指数退避。