Claude Code 529 Overloaded：原因、重試設定與解決方法

Wokey Team · 2026-09-24

簡短回答： 529 表示上游模型目前容量不足（"overloaded"，過載）。它和你的餘額、額度或 API 金鑰都無關。Claude Code 在顯示這個錯誤之前已經重試過好幾次。最快的解法是用 /model 切換模型，因為容量是按模型分開計算的。如果不急，等幾分鐘再送一次即可。

錯誤原文

在 Claude Code 中你會看到：

API Error: Repeated 529 Overloaded errors. The API is at capacity — this is usually temporary. Try again in a moment. If it persists, check https://status.claude.com.

Claude Code 的文件對這個錯誤說明了三點：

• 這是所有使用者共同遇到的暫時性容量問題。
• Claude Code 在顯示錯誤之前已經重試過好幾次。
• 529 不是你的用量上限，也不會計入你的額度。

透過 ANTHROPIC_BASE_URL 經由閘道連線時，最後一句寫的會是閘道的主機名稱，而不是 status.claude.com。

在 Wokey 上 529 從哪裡來

Wokey 自己從不產生 529；這個狀態碼一定來自上游模型。Wokey 分三步處理：

1. 上游回報過載時（例如 Anthropic 的 overloaded_error），Wokey 會先把你的請求改走同一模型的另一條上游路線重試。這一步你看不到。

2. 只有重試的路線也過載時，Wokey 才會把上游的狀態原樣傳回。HTTP 狀態碼維持 529，回應內容使用 Wokey 的標準錯誤格式，message 中是上游自己的原文：

   {"error":{"code":"upstream_overloaded","message":"Overloaded","type":"invalid_request_error"}}
   

3. 如果過載發生在回覆已經開始串流之後，它會以串流內的 error 事件送達，而不是 HTTP 529。

所以透過 Wokey 收到 529，表示同一模型的多條上游路線同時過載，通常發生在供應商那一端的尖峰時段。這些回應不帶 Retry-After 標頭；你的用戶端會依自己的退避排程重試。

和其他錯誤的區別

只有 529 和 503 代表「上游很忙」。其他狀態都需要你這一端處理。

怎麼處理

1. 等一下再送。 過載通常幾分鐘內就會解除，短暫的尖峰 Claude Code 的自動重試已經涵蓋了。

2. 用 /model 切換模型。 容量按模型分開計算，所以 Opus 過載時 Sonnet 往往還能用。在工作階段中執行 /model 選另一個模型即可，不需要重新啟動。

3. 無人值守的長時間任務，重試要更積極。 在 ~/.claude/settings.json 的 env 區塊加入：

{
  "env": {
    "CLAUDE_CODE_RETRY_WATCHDOG": "1"
  }
}

• CLAUDE_CODE_RETRY_WATCHDOG=1 會讓 Claude Code 無限重試 429 和 529 錯誤，每次嘗試之間最多退避 5 分鐘，適合整夜執行的任務。
• 只想多試幾次的話，改設 CLAUDE_CODE_MAX_RETRIES。預設是 10，上限是 15。

4. 在自己的程式碼裡，為 529 預留重試空間。 官方 Anthropic SDK 預設會對 5xx 錯誤（包括 529）重試兩次。批次任務請調高 max_retries，並在呼叫外層加上指數退避。

在 Codex 中看到 529

Codex 把 5xx 錯誤（包括 529）視為可重試：

• HTTP 層預設重試 4 次（provider 的 request_max_retries）。
• 接著串流層最多再重試 5 次（stream_max_retries）。
• 全部失敗後，錯誤會以 unexpected status 529 開頭，後面接著回應內容。

如果回應內容中的 code 是 upstream_overloaded，就是上面說的上游過載。解法相同：等待，或在 config.toml 中切換模型。完整的 Codex 設定請見 Codex config.toml 設定指南。