環境変数

CLAUDE_CODE_RETRY_WATCHDOG

評価ハーネス、CI ジョブ、リモートワーカーなど無人セッションで実行する場合は 1 を設定する。CLAUDE_CODE_MAX_RETRIES 回の試行で失敗する代わりに、429 および 529 の容量エラーを無期限にリトライする。標準速度のリクエストが、スケジュールでリセットされるゲートウェイの支払い上限に起因するものを含め、支払い上限または利用クレジット枯渇を報告する 429 を受け取った場合、Claude Code は即座に失敗する。v2.1.239 より前では、ウォッチドッグはこれらを無期限にリトライしていた。ファストモードのリクエストについては Handle rate limits を参照。ウォッチドッグは試行間で最大 5 分のバックオフを行い、レスポンスにレート制限のリセット時刻が含まれる場合はその時刻まで待つため、利用上限に達したセッションは残り時間の経過を待つ。v2.1.199 以降では、サーバーエラー、タイムアウト、接続断など他の一時的エラーに対する既定のリトライ回数も 300(およそ 3 時間のバックオフ)に引き上げられ、CLAUDE_CODE_MAX_RETRIES を明示的に設定した場合の上限 15 の制限が取り除かれる。Claude Code v2.1.186 以降が必要。

使い方・用途

  • eval harness や CI ジョブ、リモートワーカーのような無人セッションで、429 や 529 の容量エラーで即座に失敗するのを避けたい
  • 使用量制限に達したセッションで、リセットまでの残り時間を待ち切って処理を継続させたい
  • スクリプトでサーバーエラーやタイムアウト、切断などの一時的なエラーに対する既定のリトライ回数を増やし、15 の上限を外したい
英語原文(公式ドキュメントより)

Set to 1 for unattended sessions such as eval harnesses, CI jobs, or remote workers. Retries 429 and 529 capacity errors indefinitely instead of failing after CLAUDE_CODE_MAX_RETRIES attempts. Claude Code fails at once when a standard-speed request gets a 429 that reports a spend limit or exhausted usage credits, even one from a gateway spend cap that resets on a schedule. Before v2.1.239, the watchdog retried these indefinitely. For fast mode requests, see Handle rate limits. The watchdog backs off up to 5 minutes between attempts, or until the limit resets when the response carries a rate-limit reset time, so a session that hits a usage limit waits out the remaining window. On v2.1.199 or later it also raises the default retry count for other transient errors, such as server errors, timeouts, and dropped connections, to 300, roughly three hours of backoff, and removes the cap of 15 on CLAUDE_CODE_MAX_RETRIES if you set that variable explicitly. Requires Claude Code v2.1.186 or later

関連する変更履歴

v2.1.305(1件)

Added
CLAUDE_CODE_RETRY_WATCHDOG_USAGE_LIMIT_RECHECK_MS を追加した。これにより無人リトライモード(CLAUDE_CODE_RETRY_WATCHDOG)が、リセット前に解除された使用量制限を検知できるようになる。
英語原文を表示
Added CLAUDE_CODE_RETRY_WATCHDOG_USAGE_LIMIT_RECHECK_MS so unattended retry mode (CLAUDE_CODE_RETRY_WATCHDOG) notices a usage limit that was lifted before its reset

変更後

無人実行向けのリトライモード(CI ジョブなど)でも、セッション制限などの使用上限がリセット時刻を待たずに解除されたことを検知できるようになり、解除のタイミングで待機を終えて処理を再開できる。

関連ドキュメント

v2.1.301(1件)

Added
無人リトライモード(CLAUDE_CODE_RETRY_WATCHDOG)において、使用制限のリセットが遠すぎる場合に待機せずリクエストを終了させるための CLAUDE_CODE_RETRY_WATCHDOG_MAX_USAGE_LIMIT_WAIT_MS を追加した。
英語原文を表示
Added CLAUDE_CODE_RETRY_WATCHDOG_MAX_USAGE_LIMIT_WAIT_MS so unattended retry mode (CLAUDE_CODE_RETRY_WATCHDOG) ends a request at a usage limit that resets too far away instead of waiting

変更後

CI などの無人実行で CLAUDE_CODE_RETRY_WATCHDOG を有効にした際、リセットまで長い時間がある利用制限エラーでリトライを延々と待ち続けることがなくなる。この変数で最大待機時間を指定すれば、回復まで遠い制限に当たったリクエストを即座に終了させられ、ジョブが何時間も留まり続けるのを防げる。

関連ドキュメント

v2.1.295(1件)

Added
無人リトライモード(CLAUDE_CODE_RETRY_WATCHDOG)が 429 と 529 エラーで待機できる時間を制限する CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS を追加
英語原文を表示
Added CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS to limit how long unattended retry mode (CLAUDE_CODE_RETRY_WATCHDOG) waits out 429 and 529 errors

変更後

CI ジョブなどの無人セッションでリトライ待機時間が無制間に長引く代わりに、上限を設定して待機時間を制御できるようになる。

v2.1.288(1件)

Fixed
无人監視セッション(CLAUDE_CODE_RETRY_WATCHDOG)が、非常に長いレスポンスストリームの失敗後に何時間もリトライし続ける問題を修正した。Claude Code は再びストリーミングを行い、3 回タイムアウトした時点で諦めるようになった
英語原文を表示
Fixed unattended sessions (CLAUDE_CODE_RETRY_WATCHDOG) retrying for hours after a very long response stream failed; Claude Code now streams again, and gives up after three timeouts

v2.1.281(1件)

Fixed
CLAUDE_CODE_RETRY_WATCHDOG のセッションが、429/529 の待機が続いた後に最初の 5xx や切断された接続で失敗する問題、および 5xx からの長い Retry-After に対して上限なく無言でスリープする問題を修正した
英語原文を表示
Fixed CLAUDE_CODE_RETRY_WATCHDOG sessions failing on the first 5xx or dropped connection after a run of 429/529 waits, and sleeping uncapped and silently on a long Retry-After from a 5xx

関連ドキュメント

v2.1.271(1件)

Fixed
CLAUDE_CODE_RETRY_WATCHDOG 環境下で fast mode が、使用クレジットの上限に達するとターンを失敗させたり、過負荷を fast 速度でリトライしたりする問題を修正した。標準速度へフォールバックするようになった。
英語原文を表示
Fixed fast mode under CLAUDE_CODE_RETRY_WATCHDOG failing the turn on a usage-credits limit, or retrying an overload at fast speed, instead of falling back to standard speed

関連ドキュメント

v2.1.260(1件)

Fixed
エージェントチームの問題を修正した。長い API 再試行待ち(CLAUDE_CODE_RETRY_WATCHDOG 下など)の間、再試行通知が実際のメッセージを押し出すことで、インプロセスのチームメイトのトランスクリプトがメッセージを失ったり空白になったりしていた。
英語原文を表示
Fixed agent teams: an in-process teammate's transcript losing messages, or going blank, during long API retry waits (e.g. under CLAUDE_CODE_RETRY_WATCHDOG) as retry notices evicted real messages

関連ドキュメント

v2.1.239(1件)

Changed
永続リトライモード(CLAUDE_CODE_RETRY_WATCHDOG)が、組織の支出上限やクレジット残高不足のエラー時に、リセットを無期限に待つ代わりに即座に失敗するようになった
英語原文を表示
Persistent retry mode (CLAUDE_CODE_RETRY_WATCHDOG) now fails immediately on organization spend-limit and out-of-credits errors instead of waiting indefinitely for a reset

変更後

spend-limit やクレジット残高不足のエラーは、リセットを待つリトライを繰り返しても解決しないため、CI などの無人セッションで失敗に気づかず待ち続けていた問題を避けられる。即座にエラーで終了するので、ワークフローを早く失敗させて原因を把握できる。

関連ドキュメント

v2.1.199(1件)

Changed
バックグラウンド処理の堅牢性を高めるため、デフォルトのリトライ上限を 300 回に引き上げ、ハード上限の 15 回を撤廃
英語原文を表示
CLAUDE_CODE_RETRY_WATCHDOG now raises the default retry count for non-capacity transient errors to 300 and lifts the cap of 15 on CLAUDE_CODE_MAX_RETRIES

変更後

CIやリモート環境などの自動化タスクが、一時的なネットワーク断絶で失敗する確率を大幅に減らせます。

関連ドキュメント

v2.1.186(1件)

Changed
CLAUDE_CODE_MAX_RETRIES の上限が15回に変更されました。無人セッションでの利用には、代わりに CLAUDE_CODE_RETRY_WATCHDOG の使用が推奨されます。
英語原文を表示
Changed CLAUDE_CODE_MAX_RETRIES to cap at 15; for unattended sessions, use CLAUDE_CODE_RETRY_WATCHDOG instead

変更後

エラー時の挙動が予測可能になり、特に自動化スクリプトなどでの信頼性が向上します。

関連ドキュメント