Error 429 Too Many Requests

這個錯誤是什麼意思

Error 429 表示服務端理解了請求，但目前不願意繼續處理，因為請求頻率、並發、token 消耗或帳號額度觸發了限制。

在 AI API 中轉場景裡，這個回應可能來自上游模型服務，也可能來自中轉站自己的閘道。先把它當作限流或額度訊號處理，不要第一時間判斷為服務商故障。

常見原因

1. 服務商的每分鐘請求數、每分鐘 token 數、並發請求數或單模型限制被觸發。
2. 帳號沒有可用額度，預付餘額耗盡，或目前模型沒有開通可用計費。
3. 中轉站對你的 API Key 做了限流，即使上游官方 API 還有容量，也可能返回 429。
4. Claude Code、Codex、Cursor 或其他工具可能會自動重試失敗請求，把一次失敗變成很多次請求。
5. 高上下文 prompt、串流任務、批處理任務或 coding agent 循環可能比普通聊天更快消耗 token。

排查和修復步驟

1. 先等待再重試。如果回應裡有 Retry-After header，按它給出的時間等待，不要立刻重複發送同一個請求。
2. 檢查服務商控制台裡的餘額、計費狀態、每日額度、請求限制和模型級限制。
3. 降低並發，減少 max output tokens，縮短 prompt，避免多個 coding agent 會話共用同一個 API Key 同時跑。
4. 確認 Base URL 指向的是你想用的 provider。錯誤的代理配置可能把請求打到額度更小的帳號池。
5. 只有在確認目前 Key、餘額和限流規則都沒問題後，再考慮切換到更小模型或其他 provider。

API 中轉用戶要重點看什麼

先用相同的 Base URL、API Key 和模型名發一個最小請求。如果最小請求也返回 429，問題更可能在額度、計費、provider 限制或中轉站限流。

如果最小請求正常，但 coding tool 失敗，重點檢查並發和重試循環。Coding agent 在讀文件、調用工具、恢復失敗步驟時，可能快速發出很多請求。

什麼時候該換 Provider

只有在確認目前 provider 的限流就是瓶頸，而且你的請求方式沒有問題時，換 provider 才有幫助。如果是本地工具循環重試、Key 載入錯誤或餘額不足，換站並不能真正解決問題。