ネットワーク/5xxリトライ

このダイヤルは何か

ネットワーク/5xxリトライは、一時的な障害（429 Too Many Requests、5xxサーバーエラー、タイムアウト、DNS解決失敗など）に対して、同じリクエストを再送する回数と間隔を制御するダイヤルです。このダイヤルが対象とするのは「同じリクエストをそのまま送り直せば成功する見込みがある」種類のエラーだけであり、コンテンツ起因のエラー（スキーマ不適合・低品質など）は自己修正リトライ（別のダイヤル）で扱います。

AIエージェントシステムでは、LLMプロバイダへの呼び出しが処理の中核にあり、プロバイダ可用性が不安定（F7）という力学が常に働きます。プロバイダのレート制限、一時的なサーバー障害、ネットワークの瞬断は日常的に発生します。しかし従来のWebサービスのリトライとは異なり、LLM呼び出しの1回あたりのコストが高い（数千トークンを消費する）ため、無制限にリトライすると1リクエストが高コスト（F2）という力学でコストが急膨張します。

さらに重要なのが冪等性の問題です。読取操作のリトライは安全ですが、決済・データ更新・メール送信などの副作用を伴う書込操作を冪等キー無しでリトライすると、二重実行が発生します。ネットワークリトライの設計は、常に「この操作は安全にリトライできるか」という問いとセットで考える必要があります。

効かなすぎる害 ⇔ 効きすぎる害

効かなすぎる害（リトライ回数が少なすぎる/リトライしない）

リトライを行わない、または1回で諦めると、一過性の障害で処理が不必要に失敗します。

• プロバイダの429（レート制限）は数秒待てば解消されることが多いのに、即座にエラーを返してしまいます
• ネットワークの瞬断（数百ミリ秒〜数秒）で、それまでの長い処理（数十秒のLLM推論結果）が無駄になります
• 一時的な5xxエラー（502/503/504）でエージェント全体のセッションが失敗し、ユーザーに再実行を強いることになります
• 本来はリトライ1〜2回で回復する軽微な障害がセッション全体の失敗に連鎖します

効きすぎる害（リトライ回数が多すぎる/間隔が短すぎる）

リトライを過剰に行うと、以下の問題が発生します。

• コスト増幅 — LLM呼び出しのリトライは1回あたり数千トークンを消費します。5回リトライすればコストは6倍です
• リトライストーム — 複数のエージェントが同時にリトライすると、プロバイダへの負荷が雪だるま式に増大し、障害を悪化させます
• レイテンシ爆発 — リトライのたびに待ち時間が加算され、ユーザーの待ち時間が分単位に膨張します
• 二重実行 — 冪等でない書込操作のリトライで、決済が二重に走ったりメールが重複送信されたりします
• サーキットブレーカの遅延 — リトライを繰り返している間、本来であればサーキットを開いて別の戦略に切り替えるべき判断が遅れます

決め方

このダイヤルは [failure_cost] と [cost_sensitivity] の2つの駆動変数で決めます。

基本方針：指数バックオフ＋ジッタ

リトライ間隔は指数バックオフ（1秒→2秒→4秒→...）にジッタ（乱数による揺らぎ）を加えた方式を使います。ジッタにより複数クライアントのリトライタイミングが分散し、リトライストームを防ぎます。

Retry-Afterヘッダの尊重

429応答にRetry-Afterヘッダが含まれる場合は、自前のバックオフ計算よりもそちらを優先します。プロバイダが「何秒後に再送してほしいか」を明示しているのに無視すると、さらに厳しいレート制限を受けるリスクがあります。

冪等性の確認

[failure_cost] が高い書込操作（決済、データ削除、外部通知など）は、C4 冪等コマンド包装による冪等キーが無い限りリトライを禁止します。リトライが安全かどうかの判断をLLMに委ねてはいけません。操作のリトライ可否はツール定義時に静的に決めておきます。

サーキットブレーカとの連携

リトライ上限に達したら、A6のサーキットブレーカ機能でサーキットを開き、一定時間リクエストを遮断します。これにより障害中のプロバイダへの無駄なリトライを停止し、縮退ラダー（軽量モデルへのフォールバック、キャッシュ応答、静的フォールバック）に移行できます。

目安値（出発点）

設定項目	目安値	条件
リトライ回数	2〜4回	[cost_sensitivity] が高い場合は下限寄り
初回バックオフ	1〜2秒	429の場合は Retry-After を優先
バックオフ上限	30〜60秒	これ以上待つなら縮退に移行した方がよい
ジッタ	フルジッタ（0〜バックオフ値の乱数）	等間隔ジッタより分散効果が高い
非冪等書込のリトライ	禁止（冪等キー無しの場合）	状態確認後に手動で再実行

[failure_cost] が高い環境ではリトライ回数を少なく（2回程度）し、早めにサーキットブレーカへ移行します。逆に [failure_cost] が低く [cost_sensitivity] も低い環境では、4回程度まで許容してもよいでしょう。

具体的なシナリオ

シナリオ1：LLMプロバイダの429（レート制限）

最も頻繁に遭遇するリトライ対象です。プロバイダがレート制限に達すると429 Too Many Requestsを返します。多くの場合 Retry-After ヘッダが含まれており、指定された秒数待てば解除されます。

推奨される対処：

• Retry-After ヘッダの値を最優先で使います
• ヘッダが無い場合は指数バックオフ（1秒→2秒→4秒）で再送します
• 2〜3回のリトライで概ね回復します。それでも429が続く場合はサーキットブレーカを開き、別プロバイダへのフォールバックまたは縮退を検討します

シナリオ2：一時的な502/503/504エラー

プロバイダ側の一時的なサーバーエラーです。数秒〜数分で回復することが多いですが、長時間のダウンタイムに発展する場合もあります。

推奨される対処：

• 初回バックオフ1〜2秒、最大3回リトライ
• 3回失敗したらサーキットブレーカを開き、15〜60秒の遮断期間を設けます
• Half-Open状態で1リクエスト試行し、成功すれば復帰、失敗すれば再遮断します

シナリオ3：決済APIへの書込リトライ

エージェントが決済APIを呼び出す際にタイムアウトが発生した場合、「決済が完了したかどうか」が不明な状態になります。

推奨される対処：

• 冪等キー（C4）を付与した上でリトライします
• 冪等キーが無い場合はリトライ禁止です。代わりに状態確認API（GET）で決済の完了状態を確認し、未完了であれば再実行します
• [failure_cost] が高い操作のため、リトライ結果は全量ログに記録します

シナリオ4：複数プロバイダ構成でのリトライ

B7 モデル段階化で複数プロバイダを使っている場合、リトライ先を同一プロバイダではなく別プロバイダに向けることで、プロバイダ固有の障害を回避できます。

推奨される対処：

• 1回目のリトライは同一プロバイダ（一時的な障害の場合に高速回復）
• 2回目以降は別プロバイダにフォールバック
• プロバイダごとに独立したサーキットブレーカを設置します

実践的なアドバイス

• ネットワークリトライと自己修正リトライは明確に区別してください。429/5xx/タイムアウトは「同じリクエストを再送」すれば回復する見込みがあります。スキーマ不適合や低品質出力は「同じリクエストを送っても直らない」ため、エラー内容をコンテキストに追加する自己修正リトライが必要です。この2つを混同すると、リトライ戦略が崩壊します。

• 非冪等な書込操作のリトライは、冪等キー無しでは絶対に行わないでください。これは最も重大な落とし穴です。「タイムアウトしたが実は先方では処理が完了していた」というケースで二重実行が起きます。C4 冪等コマンド包装を全副作用操作に適用するか、リトライ前に状態確認を行ってください。

• リトライ予算をトークン数で管理することを検討してください。回数ベースの上限よりもトークン予算ベースの方が、コストの暴走を確実に防げます。LLM呼び出しのリトライは1回あたりのコストが大きいため、「あと何回」よりも「あといくらまで」で判断する方が合理的です。

• 全リクエストを同一のリトライポリシーで扱わないでください。プロバイダのヘルスチェック呼び出しは10回リトライしてもコストは微小ですが、大規模な推論リクエストの10回リトライはコスト爆発です。操作の重さに応じてリトライ回数を調整します。

• リトライ発生率を必ず監視してください。リトライ率が急上昇した場合、プロバイダ側の障害か、自システムの負荷超過の兆候です。G1 二層観測でリトライ率をダッシュボードに表示し、閾値超過でアラートを設定しておきます。

関連パターン

• A6 適応タイムアウト＋予算律速リトライ — リトライ戦略の中核パターンです。エラー分類、予算律速、サーキットブレーカの詳細を定義しています。
• C4 冪等コマンド包装 — 非冪等書込のリトライ安全性を担保します。ネットワークリトライとの組み合わせが必須です。
• A7 期限・予算のカスケード伝播 — リトライが全体予算を食い潰さないように、残り予算をチェックしてからリトライ可否を判断します。
• G1 二層観測 — リトライ率・サーキットブレーカの状態遷移を観測し、閾値調整のフィードバックループを構成します。