使用 Claude Code 时,很多订阅了 Claude Pro 或 Max 的开发者会遇到这样一条让人困惑的报错:API Error: Server is temporarily limiting requests (not your usage limit) 或 HTTP 429 Too Many Requests。后台查看套餐进度条明明还有大量余量,请求却被频繁拦截。
根据 Anthropic 官方错误参考文档(Error reference)与社区实际排障记录,这类报错通常不是月度或每周额度耗尽,而是由凭证串号、短时并发过高或后台重试策略未开启引起的。按以下 5 步即可快速定位并恢复:

5 步系统排查与修复步骤
第一步:运行 /status 检查是否被环境变量 ANTHROPIC_API_KEY 劫持:这是最隐蔽的头号原因。只要当前终端环境里残留了以前测试用的 ANTHROPIC_API_KEY,Claude Code 就会优先走该 API Key 计费,而跳过你的 claude.ai Pro/Max 订阅身份;如果这把旧 Key 处于免费层或 Tier 1 低速率档位,随便发几轮就会触发 429。在终端输入 /status 核对当前生效的登录凭证,若发现误用了 API Key,立即在 macOS/Linux 下执行 unset ANTHROPIC_API_KEY(Windows PowerShell 执行 Remove-Item Env:ANTHROPIC_API_KEY),随后重新运行 /login。
第二步:对照报错措辞,区分 429 限流、529 过载与真实套餐上限:如果报错提示里带有具体的重置时间戳(例如 resets at ...),说明确实触及了 5 小时滚动窗口或每周订阅配额,只能等待重置;如果提示 Overloaded 或 HTTP 529,说明 Anthropic 对应模型节点全网高负载,可用 /model 临时切换到 Sonnet 或 Haiku 绕过;只有提示 not your usage limit 或 429 rate_limit_error 时,才属于短时速率节流(通常持续数十秒到几分钟),此时切忌手动疯狂按重试,否则只会叠加请求计数。
第三步:关闭多余并行桌面端标签页与并行子代理:在 Claude 桌面端或终端中同时挂起 6 个及以上活跃 Code 会话,或者在一个任务里放任模型同时派生大量并行 Subagents,极易在数秒内打满每分钟请求数(RPM)或输入 Token 速率(ITPM)红线。建议将同时运行的活跃会话控制在 1 到 2 个以内。
第四步:将 Claude Code 升级至最新稳定版:旧版客户端在遇到短时 429 时容易直接中断轮次;较新版本(2.1.199 及以上,当前最新为 2.1.323)内置了最多 10 次指数退避自动重试(终端会显示 Retrying in Ns · attempt x/y),在 429 报错抛给用户前就能自动扛过短时波动。执行 claude update 即可更新。
第五步:为后台无人值守任务开启看门狗(Retry Watchdog):如果你在跑 claude -p 无界面脚本或夜间长任务,默认的 10 次指数退避在遇到持续数分钟的限流时仍可能耗尽退出。此时可在启动命令前设置环境变量 CLAUDE_CODE_RETRY_WATCHDOG=1,让客户端在遇到 429 和 529 时持续守护重试直至恢复;若需限制最长等待时间,可搭配设置 CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS=3600000(最长等待 1 小时)。
