Claude Media
Claude Codeで529 Overloadedが続くとき — リトライの上限と待ち方
Claude CodeTips

Claude Codeで529 Overloadedが続くとき — リトライの上限と待ち方

Claude Codeの既定リトライは10回で、529が数分続くと諦めます。待ち時間を伸ばす環境変数、無人実行向けの再試行モード、サブエージェントと代替モデルの扱いを解説します。

読了目安 約9分

Claude Codeで529 Overloadedが出続けるのは、Claude Codeが待つ時間より、混雑が続く時間のほうが長いからです。既定では最大10回の再試行を、指数的に伸びる待ち時間で行い、それでも通らなければAPI Error: Repeated 529 Overloaded errorsでターンを終えます。この記事では、待ち時間を伸ばす3つの手段と、伸ばしても効かない場面を順に見ます。

529が続いても自動で戻らないのはなぜか

529はAPI側が一時的に容量いっぱいになったことを示すステータスで、ユーザーの使用量上限とは無関係です。エラーページにも、529は使用量の枠を消費しないと書かれています。

問題は再試行の長さです。エラーページの「Automatic retries」は、一時的な失敗を最大10回まで指数バックオフで再試行すると説明しています。GitHubのissue #81330（2026-07-26起票、オープンのまま）の報告者は、v2.1.220の挙動を次のように整理しました。

  • 待ち時間は500ミリ秒から倍々に増え、1回あたり32秒で頭打ちになる
  • 10回分を足すと約160秒（約2.5分）で、ジッター（ゆらぎ）が0〜25%加わる
  • 混雑が数十分続けば、その間に送るターンはすべて再試行を使い切る

この数字は報告者がバイナリ内の文字列から読み取った値で、ドキュメントには載っていません。計算自体は合います。0.5、1、2、4、8、16秒に続けて32秒が4回で、合計159.5秒です。

同じissueは、ほかに次の挙動も挙げています。いずれも報告者の読み取りで、Anthropicによる確認はありません。

  • Retry-Afterヘッダーが60秒を超えると、待たずに諦める
  • APIキー認証のOpus・Fable・Mythos系モデルでは、529が3回続くと打ち切る
  • 一部のバックグラウンド問い合わせは、最初の529で再試行なしに捨てる

2つ目に近い挙動は、公式ドキュメントにも出てきます。APIキーやサードパーティープロバイダー経由でOpus・Fable・Mythos系の過負荷が続くと再試行をやめる、という環境変数FALLBACK_FOR_ALL_PRIMARY_MODELSの説明です。この変数の癖はFALLBACK_FOR_ALL_PRIMARY_MODELSの解説にまとめています。

待ち時間を伸ばす3つの手段

issue起票時に未記載だった環境変数は、その後ドキュメントに載り、さらに増えました。529に効くものを、待ち方の強さ順に並べます。

手段効き方必要なバージョン
CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS効き方529だけ、最初の待ち時間を500から最大32000ミリ秒に引き上げる必要なバージョンv2.1.292以降
CLAUDE_CODE_MAX_RETRIES効き方再試行の回数を変える。既定10、上限15必要なバージョン上限15はv2.1.186以降
CLAUDE_CODE_RETRY_WATCHDOG=1効き方429と529を回数無制限で再試行する必要なバージョンv2.1.186以降

最初の待ち時間を伸ばす

CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MSは、529専用のバックオフの起点を変えます。値は500〜32000の整数をカンマなしで書き、範囲外は未設定として扱われます。

上限32秒が変わらないと仮定すると、10回分の合計は次のように伸びます。

起点（ミリ秒）待ち時間の並び（秒）合計
500（既定）待ち時間の並び（秒）0.5、1、2、4、8、16、32×4合計約160秒
2000待ち時間の並び（秒）2、4、8、16、32×6合計約222秒
32000待ち時間の並び（秒）32×10合計320秒

起点を最大にしても、待てるのは約5分強です。上の表は報告者の読み取った上限32秒を前提にした自前の計算で、実際の待ち時間とは差が出ることがあります。数十分続く混雑には届かないので、これは「短い波をまたぐ」ための調整だと考えると使いやすくなります。

回数を増やす

CLAUDE_CODE_MAX_RETRIESで増やせるのは15回までです。待ち時間の上限が変わらない以上、効果は数十秒分にとどまります。逆に、スクリプトで早く失敗させたいときは値を下げます。

再試行モードで混雑が終わるまで待つ

数十分以上の混雑を待ち切るなら、CLAUDE_CODE_RETRY_WATCHDOG=1です。429と529を無制限に再試行し、待ち時間は最大5分まで伸びます。それ以外の一時的な失敗（サーバーエラー、タイムアウト、接続切れ）の既定回数も300に上がり、およそ3時間分のバックオフになります。

エラーページは、CIやevalハーネス、リモートワーカーのような無人セッション向けと位置づけています。ただし429のうち、支出上限やクレジット切れを告げるものは、v2.1.239以降は待たずに失敗します。使用量の枠が戻らない限り、待っても通らないためです。

無限に待つのが怖い場合は、v2.1.295で追加されたCLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MSで、1リクエストあたりの待ち時間に上限を付けられます。たとえば30分なら1800000です。上限に達すると、次の429・529でそのリクエストは終わります。

CLAUDE_CODE_RETRY_WATCHDOG=1 \
CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS=1800000 \
claude -p "テストを実行して失敗を直して"

毎回付けたくない場合は、設定ファイルのenvに書きます。

{
  "env": {
    "CLAUDE_CODE_RETRY_WATCHDOG": "1",
    "CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS": "1800000"
  }
}

再試行モードを有効にすると、CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MSは効かなくなります。fast modeで送ったリクエストにも効きません。fast modeは別の扱いで、レート制限に当たると標準速度へ落ちます。

設定を変えた直後に起きること

issue #81330のコメントには、設定の変更が再試行にどう反映されるかの報告が付いています。Amazon Bedrock経由でFable 5を使うユーザーが、セッションの途中でsettings.jsonのCLAUDE_CODE_RETRY_WATCHDOGを外し、CLAUDE_CODE_MAX_RETRIESを2にしました。その後の429で、スピナーはattempt 5/2と表示されたそうです。

待ち時間は短くなったのに、回数は新しい上限を超えて増えました。報告者は、設定の再読み込みが一部だけ反映された可能性と、429が別の再試行経路を通る可能性の2つを挙げ、どちらかは切り分けていません。ドキュメントには、設定ファイルのenvは変更時に実行中のセッションへ再適用されるとあります。それでも、再試行の設定は新しいセッションで確かめるほうが確実です。

issue本文は別の食い違いも指摘しています。スピナーのattempt N/10が見かけの予算で、実際の打ち切りはそれより早いという内容です。これも報告者の読み取りなので、画面の分母だけを頼りに待ち時間を見積もらないほうが安全です。

試すときは、まず新しいセッションで次のように1回だけ実行し、スピナーの分母が意図した値になっているかを見ます。

CLAUDE_CODE_MAX_RETRIES=3 claude

分母が3にならない場合は、設定の書き方や読み込み先を見直します。

待っている間の画面と、待たずに変えられること

再試行中のスピナーにはRetrying in 12s · attempt 4/10のようなカウントダウンが出ます。理由のラベルは、3回目の試行から具体的な内容に切り替わります。529のときは、その下の行にstatus.claude.comが案内されます。

混雑はモデルごとに追跡されます。そのためモデルを替えれば通ることがあります。選択肢は3つあります。

手順

529が続くときの手の打ち順

  1. 1

    状況ページを見る

    status.claude.comで容量に関する告知が出ているかを見ます。告知があれば、待つ時間の見積もりになります。

  2. 2

    モデルを替える

    /modelで別のモデルへ切り替えます。Opus is experiencing high loadのような案内が出た場合は、その提案に従う形です。

  3. 3

    代替モデルを事前に決めておく

    fallbackModelに連鎖を書いておくと、過負荷が続いたターンだけ次のモデルに回ります。

代替モデルの連鎖は、過負荷や利用不可のときに切り替わります。認証、課金、レート制限、リクエストサイズ、通信の各エラーでは切り替わりません。切り替えは現在のターンだけで、次のメッセージはまたプライマリのモデルから試します。連鎖は3モデルまでです。

claude --fallback-model sonnet,haiku

設定ファイルに残すなら、"fallbackModel": ["claude-sonnet-5", "claude-haiku-4-5"]の配列で書きます。設定の詳細と、切り替わったことに気づく方法はfallbackModelの設定記事で扱っています。

サブエージェントが529で止まったとき

issue #82520には、長時間セッションでバックグラウンドのサブエージェントが529で打ち切られ、編集途中のファイルが残ったという報告があります。報告者は、サブエージェントのプロンプトに「529なら待って再試行する」と書いても、モデルが動く前にハーネス側が止めてしまうと見ています。この見立ては報告者のもので、公式の仕様として確認できたわけではありません。打ち切られた後に編集途中のファイルが気になるときは、git statusで未コミットの変更を確かめてから再実行できます。

現在のドキュメントから言えるのは次の3点です。

  • 再試行を使い切るとAgent terminated early due to an API error: <詳細>が返る。v2.1.199以降の表示
  • 連鎖の代替モデルは、v2.1.247以降サブエージェントにも適用される。サブエージェントだけ代替モデルで続き、セッション側のモデルは変わらない
  • エラーが解消したら、Claudeにタスクの再実行を頼むか、サブエージェントを再開する

途中まで編集されたファイルが残る点は、公式の説明にはありません。長く動かすサブエージェントを使うなら、実行前にワークツリーをコミットしておくと、打ち切られた後に差分を見て戻すか続けるかを決められます。

構成別の選び方

状況先に試すもの
対話中に数分だけ529が出る先に試すもの待つか/modelで切り替える
対話中に529が何度も続く先に試すものfallbackModelとCLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS
CIや夜間バッチで失敗させたくない先に試すものCLAUDE_CODE_RETRY_WATCHDOG=1とCLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS
スクリプトで早く失敗させたい先に試すものCLAUDE_CODE_MAX_RETRIESを下げる
APIキーでOpus・Fableを使う先に試すもの過負荷での再試行打ち切りを前提に代替モデルを置く

再試行を使い切った後の挙動を検知して通知する方法は、retry exhaustionの検知手順にあります。429と529の見分け方や、枠の回復の考え方は429とoverloadedの違いの記事にまとめています。

まとめ

既定の再試行は約2.5分で終わり、起点の待ち時間を最大にしても約5分強です。数十分続く混雑を越えるには、無人実行なら再試行モード、対話なら代替モデルへの切り替えが現実的な選択肢になります。待ち時間の上限や回数は、それぞれの環境変数で調整できます。

v2.1.295で入った待ち時間の上限はv2.1.295のリリースノートでも触れています。issue #81330はオープンのままで、既定値そのものが変わるかは分かりません。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →