【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 Code
- CI/CD 并行任务调用同一 API Key
- 工具无限循环导致大量请求
- 使用免费额度或低级别 API 套餐
- 上下文过大导致每次请求消耗大量 Token
2. 原因分析
核心原理拆解
大量 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 # 步骤 2：CI/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_KEY=sk-ant-api03-KEY1 # 开发用 # CI/CD 用另一个 Key方案五：配置重试和退避
# 步骤 1：Claude Code 通常会自动重试 429 # 如果不自动重试，手动等待后重试 # 步骤 2：在 settings.json 中配置重试 cat > ~/.claude/settings.json << 'EOF' { "maxRetries": 3, "retryDelay": 5000 } EOF # 步骤 3：CI/CD 中手动退避 for i in 1 2 3; do output=$(claude --print "task" 2>&1) 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. 常见问题 FAQ
5.1 Anthropic API 的速率限制是多少
取决于套餐级别：
- 免费：较低限制
- Tier 1：50 RPM, 100K TPM
- Tier 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
