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 のドキュメントは、このエラーについて 3 つの点を挙げています。

• すべてのユーザーに共通する一時的な容量の問題である。
• Claude Code は表示する前に何度かリトライしている。
• 529 は使用制限ではなく、クォータにもカウントされない。

ANTHROPIC_BASE_URL でゲートウェイ経由で接続している場合、最後の文には status.claude.com の代わりにゲートウェイのホスト名が入ります。

Wokey で 529 が発生する仕組み

Wokey 自身が 529 を生成することはありません。このステータスは常に上流のモデルから来ます。Wokey は 3 つのステップで処理します。

1. 上流が過負荷を報告すると（たとえば Anthropic の overloaded_error）、Wokey はまず同じモデルの別の上流ルートでリクエストをリトライします。これはユーザーからは見えません。

2. リトライ先も過負荷だった場合にのみ、Wokey は上流のステータスをそのまま返します。HTTP ステータスは 529 のままです。ボディは Wokey の標準エラー形式で、message には上流自身の文言が入ります。

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

3. 返答のストリーミングが始まった後に過負荷が起きた場合は、HTTP 529 ではなくストリーム内の error イベントとして届きます。

つまり 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 は、529 を含む 5xx エラーをデフォルトで 2 回リトライします。バッチジョブでは max_retries を増やし、呼び出しを指数バックオフで囲んでください。

Codex で 529 が出る場合

Codex は 529 を含む 5xx エラーをリトライ可能として扱います。

• HTTP レイヤーはデフォルトで 4 回リトライします（プロバイダーの request_max_retries）。
• 続いてストリームレイヤーがさらに最大 5 回リトライします（stream_max_retries）。
• それらがすべて失敗すると、エラーは unexpected status 529 で始まり、その後にレスポンスボディが続きます。

そのボディの code が upstream_overloaded なら、上で説明した上流の過負荷です。対処も同じで、待つか、config.toml でモデルを切り替えてください。Codex の設定全体は Codex config.toml ガイドをご覧ください。