【Bug已解决】Rate limit exceeded / 429 Too Many Requests — Claude Code API 速率限制解决方案

【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 无法继续发送请求

原因分类表

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 alerts

4. 各方案对比总结

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

1. 使用/compact压缩上下文
2. 避免读取大文件
3. 切换到 Haiku 模型（更省 Token）
4. 减少会话历史

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. 总结

1. 根本原因：速率限制最常见原因是超过每日 Token 限制（40%）和每分钟请求限制（25%）
2. 最佳实践：使用/compact压缩上下文减少每次请求的 Token，使用/model haiku切换到更省 Token 的模型
3. 并发控制：不要同时开多个 Claude Code 终端，CI/CD 中串行执行并间隔 5-10 秒
4. 监控用量：定期使用/status和/context检查 Token 使用量，在 Anthropic Console 设置预算提醒
5. 最佳实践建议：为开发和 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