Claude Code 429 rate_limit_error 修复

Claude Code 提示速率限制（429 rate_limit_error）时，说明请求被 ModelGate 网关按配额策略拒绝了。多数情况是余额不足或并发过高，按本文排查即可恢复。

错误表现

请求被拒绝，提示达到速率限制，例如：

Error: rate_limit_error
429: rate limit reached

错误含义

HTTP 429 rate_limit_error 表示当前配额已用尽或被限流：网关在单位时间内收到的请求超出了账户允许的范围。

最常见原因

• ModelGate 账户余额不足或额度已用完
• 分组倍率设置导致请求额度被快速消耗
• 短时间内并发请求过多，触发限流
• 账户本身存在并发数上限

macOS / Linux 修复步骤

1. 登录 ModelGate 后台，进入 个人中心 查看余额与用量。
2. 检查当前 Key 所在分组的 分组倍率，确认没有被错误调高。
3. 降低 Claude Code 并发：在 ~/.claude/settings.json 中确认没有同时运行多个 claude 会话。
4. 减少单次请求的上下文长度，避免一次消耗过多额度。

Windows 修复步骤

1. 登录 ModelGate 后台，在 个人中心 查看余额。
2. 检查 C:\Users\{用户名}\.claude\settings.json 中的分组配置。
3. 关闭多余的 Claude Code 窗口，避免并发挤占配额。
4. 等待几分钟后重试（限流通常按分钟窗口计算）。

curl 验证

# macOS / Linux
curl -i https://modelgate.app/v1/messages \
  -H "x-api-key: 你的Key" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-4-6","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}'

# Windows PowerShell
curl.exe -i https://modelgate.app/v1/messages `
  -H "x-api-key: 你的Key" `
  -H "anthropic-version: 2023-06-01" `
  -H "content-type: application/json" `
  -d '{"model":"claude-sonnet-4-6","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}'

• 返回 429 → 确认为配额/限流问题，检查余额与分组倍率。
• 返回正常 → 问题可能出在客户端并发，降低频率重试。

ModelGate 示例

检查账户配额状态（若网关开放该端点）：

curl https://modelgate.app/api/quota \
  -H "Authorization: Bearer 你的Key"

检查清单

• 账户余额充足，未欠费
• 分组倍率正常，未被人为调高
• 没有多个 Claude Code 会话并发运行
• 已等待几分钟再重试（限流窗口已过）
• curl 验证确认 429 已消失

相关教程

• 模型与计费说明 — 余额、倍率与配额规则
• Claude Code 常见报错排查 — 全部错误码速查
• Claude Code 接入教程 — 完整配置步骤