使用 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 小時)。
