【Bug已解决】Rate limit exceeded / 429 Too Many Requests — Claude Code API 速率限制解决方案1. 问题描述在频繁使用 Claude Code 时API 返回 429 速率限制错误Error: 429 Too Many Requests {type:error,error:{type:rate_limit_error,message:Number of request tokens has exceeded your daily rate limit}} # 或并发限制 Error: 429 Too Many Requests {type:error,error:{type:rate_limit_error,message:Concurrent requests exceeded}} # 或每分钟请求限制 Error: 429 Rate limit: 50 requests per minute这个问题在以下场景中特别常见长时间密集使用 Claude Code多个终端同时运行 Claude CodeCI/CD 并行任务调用同一 API Key工具无限循环导致大量请求使用免费额度或低级别 API 套餐上下文过大导致每次请求消耗大量 Token2. 原因分析核心原理拆解大量 API 请求 → 超过 Anthropic 的速率限制 ↓ API 返回 429 Too Many Requests ↓ Claude Code 无法继续发送请求原因分类表限制类型具体表现占比每日 Token 限制超过日额度约 40%每分钟请求限制RPM 超限约 25%并发请求限制多终端/多任务约 20%免费额度耗尽免费计划限制约 10%工具循环无限调用消耗配额约 5%3. 解决方案方案一等待限制重置最推荐# 步骤 1查看限制信息 # 429 错误通常包含 reset 时间 # rate_limit_error: resets at 2024-01-16T00:00:00Z # 步骤 2等待到重置时间 # 每日限制通常在 UTC 午夜重置 date -u # 查看当前 UTC 时间 # 步骤 3计算等待时间 # 如限制在 UTC 00:00 重置 # 等待到该时间后重试方案二减少 Token 消耗# 步骤 1使用 /compact 压缩上下文 /compact # 减少每次请求的输入 Token # 步骤 2使用更小的模型 /model haiku # Haiku 消耗更少 Token 且限制更高 # 步骤 3避免读取大文件 # 只读取必要的代码行 # 步骤 4使用 /clear 重置上下文 /clear # 完全清空上下文减少 Token 消耗方案三避免并发请求# 步骤 1不要同时开多个 Claude Code 终端 # 关闭其他终端中的 Claude Code # 步骤 2CI/CD 中串行执行 # 不要并行运行多个 claude --print # 改为串行: for task in task1 task2 task3; do claude --print $task --max-turns 10 sleep 5 # 间隔 5 秒 done # 步骤 3使用队列管理 # 确保同一时间只有一个请求方案四升级 API 套餐# 步骤 1在 Anthropic Console 查看当前套餐 # console.anthropic.com → Settings → Billing # 步骤 2升级到更高级别 # 更高级别有更高的速率限制 # 步骤 3或使用多个 API Key 分散负载 # 不同的任务使用不同的 Key export ANTHROPIC_API_KEYsk-ant-api03-KEY1 # 开发用 # CI/CD 用另一个 Key方案五配置重试和退避# 步骤 1Claude Code 通常会自动重试 429 # 如果不自动重试手动等待后重试 # 步骤 2在 settings.json 中配置重试 cat ~/.claude/settings.json EOF { maxRetries: 3, retryDelay: 5000 } EOF # 步骤 3CI/CD 中手动退避 for i in 1 2 3; do output$(claude --print task 21) if echo $output | grep -q 429; then echo Rate limited, waiting $((i*60))s... sleep $((i*60)) else break fi done方案六监控 Token 使用量# 步骤 1使用 /status 查看配额 /status # 步骤 2使用 /context 查看 Token 使用 /context # 步骤 3在 Anthropic Console 查看用量 # console.anthropic.com → Usage # 步骤 4设置预算提醒 # Console → Settings → Budget alerts4. 各方案对比总结方案适用场景推荐指数难度方案一等待重置即时解决⭐⭐⭐⭐⭐低方案二减少 Token预防⭐⭐⭐⭐⭐低方案三避免并发多终端⭐⭐⭐⭐⭐低方案四升级套餐长期⭐⭐⭐⭐低方案五配置重试CI/CD⭐⭐⭐⭐低方案六监控用量预防⭐⭐⭐⭐⭐低5. 常见问题 FAQ5.1 Anthropic API 的速率限制是多少取决于套餐级别免费较低限制Tier 150 RPM, 100K TPMTier 2-4更高限制具体限制在 Console 中查看5.2 429 错误多久重置每分钟限制60 秒后重置每日限制UTC 午夜重置并发限制请求完成后释放5.3 如何查看剩余配额在 Anthropic Console 的 Usage 页面查看或在 Claude Code 中使用/status。5.4 多个 API Key 能分散限制吗可以。每个 Key 有独立的速率限制。使用不同的 Key 运行不同的任务可以有效分散负载。5.5 Claude Code 会自动重试 429 吗较新版本会自动指数退避重试。如果仍然失败手动等待后重试。5.6 如何减少每次请求的 Token使用/compact压缩上下文避免读取大文件切换到 Haiku 模型更省 Token减少会话历史5.7 CI/CD 中的速率限制CI/CD 中使用--print模式串行执行间隔 5-10 秒避免并发限制。5.8 工具循环消耗配额怎么办按 Escape 中断循环使用/compact清除循环状态。参考 C28工具无限循环。5.9 免费额度用完了升级到付费计划或等待免费额度重置通常每月。5.10 排查清单速查表□ 1. 查看 429 错误中的 reset 时间 □ 2. /status 和 /context 检查用量 □ 3. /compact 压缩上下文减少 Token □ 4. /model haiku 切换到更省的模型 □ 5. 关闭其他终端避免并发 □ 6. CI/CD 串行执行 sleep 间隔 □ 7. Console 查看用量和限制 □ 8. 考虑升级 API 套餐 □ 9. 多 Key 分散负载 □ 10. 设置预算提醒6. 总结根本原因速率限制最常见原因是超过每日 Token 限制40%和每分钟请求限制25%最佳实践使用/compact压缩上下文减少每次请求的 Token使用/model haiku切换到更省 Token 的模型并发控制不要同时开多个 Claude Code 终端CI/CD 中串行执行并间隔 5-10 秒监控用量定期使用/status和/context检查 Token 使用量在 Anthropic Console 设置预算提醒最佳实践建议为开发和 CI/CD 使用不同的 API Key分散速率限制负载并在 CI/CD 中配置指数退避重试故障排查流程图flowchart TD A[429 Rate Limit] -- B[查看错误中的 reset 时间] B -- C{是日限制还是 RPM?} C --|日限制| D[等待到 UTC 午夜重置] C --|RPM| E[等待 60 秒] D -- F[/compact 压缩上下文] E -- F F -- G[/model haiku 切换模型] G -- H{限制解除?} H --|是| I[✅ 继续工作] H --|否| J[检查并发终端] J -- K{多个终端运行?} K --|是| L[关闭其他终端] K --|否| M[Console 查看用量] L -- I M -- N{接近上限?} N --|是| O[升级 API 套餐] N --|否| P[使用多 Key 分散] O -- I P -- I
