AI API retry strategy は、モデルへのリクエストが失敗したり、遅くなったり、一部の結果しか返らなかったりした後に、アプリケーションが何をすべきかを決めるポリシーです。間違ったポリシーは高くつきます。すべてのエラーをリトライするとクォータ圧迫が増え、早すぎるモデル切り替えは回答品質を変え、対話型の処理をキューに回すとユーザーは待たされ、安全性や認証の失敗で fail open にすると実際の障害を隠してしまいます。
このガイドは、AI ゲートウェイ、マルチプロバイダールーター、または OpenAI 互換の base URL を使う本番チーム向けの実践的な判断レーダーです。同じプロバイダーをいつ再試行するか、いつモデルを切り替えるか、いつ処理をキューに入れるか、そしていつ fail closed にするかを扱います。AI API retry strategy の目的は、どんなコストを払ってでもすべてのリクエストを成功させることではありません。目的は、悪いリクエスト、認証問題、クォータ枯渇、安全でないフォールバック、ルーティング障害を覆い隠さずに、一時的な障害から回復することです。
Flatkey はこの問題に適しています。公開されている製品説明が、1つの API キー、https://router.flatkey.ai/v1 の OpenAI 互換 base URL、明確な価格設定、統合請求、そしてキー・使用量・ルーティングのための1つのダッシュボードを中心にしているからです。Flatkey は自動切り替えと負荷分散についても説明しています。とはいえ、それらの機能にも明示的な retry policy が必要で、チームがなぜリクエストを再試行したのか、モデルを変更したのか、キューに入れたのか、あるいは fail closed にしたのかを説明できるようにする必要があります。
AI API リトライ戦略の階層: すぐ使える答え
この意思決定の階層を、AI API リトライ戦略の価値ある資産として使ってください。これにより、リトライの挙動を「とにかく再試行する」という広いルールではなく、失敗の責任者、ユーザーのワークフロー、影響範囲に結び付けられます。
| 障害シグナル | デフォルトの対応 | エスカレーションの条件 | 停止条件 |
|---|---|---|---|
| プロバイダーがリクエストを受け付ける前のネットワークタイムアウト | 操作が冪等であるか、クライアントのリクエスト ID を使用している場合は、ジッター付きバックオフで 1 回リトライします。 | リトライ予算を使い切り、フォールバック先が同じワークフロー向けに承認されている場合は、ルートを切り替えます。 | ルート予算に達したら停止し、制御された「後で再試行」レスポンスを返します。 |
| リトライ指針付きの HTTP 429 レート制限 | 返された待機シグナルに従い、呼び出し元の速度を落とし、同時実行数を減らします。 | バックグラウンド作業をキューに入れるか、別クォータのある承認済みルートへ切り替えます。 | クォータが枯渇した、予算上限に達した、または許可されたルートが残っていない場合はクローズドで失敗します。 |
| HTTP 500、502、503、504、またはプロバイダーの過負荷 | 指数バックオフとジッターを使って少数回リトライします。 | フォールバックが品質とポリシーの要件を満たすことを確認した後にのみ、モデルやプロバイダーを切り替えます。 | リクエストがレイテンシ、トークン、コスト、または試行回数の上限を超える場合は停止します。 |
| 400 の無効なリクエスト、スキーマエラー、未対応パラメータ、またはコンテキスト超過 | 変更なしでは再試行しません。リクエストを修正する、コンテキストを縮小する、またはユーザーが修正可能なエラーを返します。 | 製品がその挙動とコストの変化を受け入れる場合に限り、より大きいコンテキストを持つモデルへルーティングします。 | 同種のリクエスト形状エラーが繰り返される場合はクローズドで失敗します。 |
| 401、403、キー無効、IP 未承認、または権限失敗 | クローズドで失敗し、キーの所有者に通知します。 | キーをローテーションするか、オペレーターのワークフローを通じてアカウントアクセスを修復します。 | セキュリティポリシーが明示的に許可していない限り、別のアカウントへ静かにフォールバックしないでください。 |
| 安全ブロック、ポリシーブロック、ツール認可失敗、またはデータ境界の問題 | 安全なメッセージでクローズドに失敗し、ポリシー上の理由をログに記録します。 | ブロックが誤っている、または顧客影響があるように見える場合はレビューへエスカレーションします。 | 答えを得るためだけに、制約の緩いモデルで再試行しないでください。 |
| ストリーミングが開始した後に停止または切断される | 操作を安全に再生でき、ユーザー体験が新しい応答を許容する場合にのみ再試行します。 | ログでストリームレベルの失敗が繰り返し示された後は、今後のリクエストのルートを切り替えます。 | UI がそれを前提に設計されていない限り、部分的に配信された回答に 2 つ目のモデル回答を追加しないでください。 |
盲目的なリトライループがAI製品を壊す理由
ほとんどのWebサービスは、一時的な障害に対して標準的なリトライパターンを使えます。AI APIは、リクエストが高コストで、状態を持ち、ストリーミングされ、ツールを使い、モデル依存であるため、より慎重な対応が必要です。盲目的なLLM API retriesループは、次の4つの失敗を引き起こす可能性があります。
- クォータの増幅: 429を過度に積極的に再試行すると、すでに制約されているリクエスト容量やトークン容量を消費してしまう可能性があります。
- 品質の変動: フォールバックモデルは異なる回答を返したり、ツールパターンを無視したり、出力形式を変えたりすることがあります。
- コストの想定外増加: フォールバックの成功が、特に長いコンテキスト、推論、画像、動画処理では、主要ルートより高コストになることがあります。
- 障害の隠蔽: ログがリトライチェーンを保持していないと、最終的な成功によって5回の失敗試行が見えなくなることがあります。
したがって、優れたAI API retry strategyは、ルーティングポリシーであり、可観測性ポリシーであり、プロダクトポリシーでもあります。どの回復が許可されるのか、どの証拠を記録しなければならないのか、そして回復に失敗した場合にどのようなユーザー体験が許容されるのかを明確に示す必要があります。
再試行する前に失敗を分類する
すべてのAI API 再試行戦略は、正規化された障害分類から始めてください。プロバイダのドキュメントは異なりますが、運用上のカテゴリはポリシーに落とし込めるほど安定しています。
| Class | Examples | Owner | Retry Posture |
|---|---|---|---|
| Caller defect | Malformed JSON, invalid parameter, unsupported tool schema, context too long. | Application or prompt pipeline. | Do not retry unchanged. |
| Authentication or permission | Invalid key, disabled key, project membership, IP allowlist, account permission. | Credential owner or security owner. | Fail closed and alert. |
| Rate limit | Requests per minute, tokens per minute, acceleration limits, concurrency limits. | Traffic owner and quota owner. | Back off, queue, reduce concurrency, or switch approved quota pool. |
| Quota or budget exhausted | Credits depleted, monthly spend cap, team quota, customer quota, prepaid balance limit. | Finance, plan owner, or customer owner. | Fail closed or queue behind approval; do not spend through another budget silently. |
| Transient provider failure | Internal server error, overloaded service, temporary gateway error, timeout. | Provider or network path. | Retry with a small budget, then route fallback if approved. |
| Policy or safety block | Moderation block, restricted output, data boundary, tool authorization failure. | Safety, security, or product policy. | Fail closed unless a human-approved remediation path exists. |
OpenAI のエラーコードガイドでは、429 のレート制限をクォータ枯渇から区別し、500 および 503 のケースを待機後に再試行する状況として文書化し、認証の問題は再試行候補ではなくキーまたは組織の修正として扱っています。Anthropic のエラードキュメントでも、invalid request、authentication、permission、rate limit、API error、overloaded の各カテゴリが同様に分けられています。これらの違いが、ステータスコードだけでは不十分な理由です。ゲートウェイはプロバイダのエラータイプと安全なエラーコードをログに保持する必要があります。
同じモデルを再試行するタイミング
失敗が一時的に見え、リクエストを安全に再実行でき、再試行によって障害が悪化しない場合は、同じモデルを再試行します。これは AI API 再試行戦略 の中で最も範囲が狭い、実用的な部分です。
同じ経路での再試行候補としては、以下が挙げられます。
- プロバイダーがリクエストを受け付ける前の接続タイムアウト。
- 一時的な 500、502、503、または 504 の応答。
- 短い待機ウィンドウがあり、かつユーザーの残りレイテンシ予算が十分あるレート制限応答。
- ユーザーに見えるトークンが一切送信される前のストリーミング初期化失敗。
同期したスリープではなく、ジッター付き指数バックオフを使用します。Google Cloud の再試行ガイダンスでは、ジッター付きの打ち切り指数バックオフが、集中再試行を避けるための標準的な再試行パターンとして説明されています。AI API では、ワークフローごとに小さな再試行予算も追加してください。対話型チャットのリクエストなら 1 回か 2 回の試行で十分です。夜間の要約バッチはより長く待機し、より慎重に再試行できます。決済、安全性、または顧客アクションのワークフローは、より厳格であるべきです。
各同じ経路での再試行では、試行インデックス、ルート、利用可能であればプロバイダーのリクエスト ID、ステータスコード、エラークラス、待機時間、最終結果をログに記録する必要があります。これを AI API 可観測性ログ のチェックリストと組み合わせることで、最終的な成功によって失敗した試行が見えなくなるのを防げます。
モデルまたはプロバイダーを切り替えるタイミング
モデルフォールバックのリトライは、単なる別のリトライではありません。モデル、プロバイダー、アカウント、コスト項目、挙動、そして場合によってはコンプライアンス境界まで変わります。フォールバックがそのワークフローに対して事前承認されている場合にのみ切り替えてください。
次のすべてが当てはまる場合に、モデルまたはプロバイダーを切り替えます。
- プライマリ経路が短いリトライ予算を使い切った、またはプロバイダー側の障害を返した。
- フォールバックモデルが、同じデータクラス、顧客ティア、エンドポイントファミリー、ツールの挙動、および出力形式について承認されている。
- プロダクトオーナーが品質差とユーザー体験を受け入れている。
- 財務オーナーがコストとクォータの差を受け入れている。
- ログに要求された経路と選択された経路の両方が記録される。
リクエストが不正な形式である場合、認可されていない場合、安全ポリシーでブロックされている場合、またはフォールバックが対応していないプロバイダー固有の機能に紐づいている場合は、切り替えないでください。Vercel の AI Gateway のモデルフォールバックのドキュメントでは、失敗や利用不可から回復する方法として、順序付けられたフォールバックモデルが説明されています。これは有用な公開ルーティングパターンとして扱いつつ、実運用でフォールバックを使う前に、必ず自社の受け入れテストを定義してください。
Flatkey の購入者にとって、運用上の論点は具体的です。ある上流経路でエラーが出たとき、どのフォールバック経路が許可されるのか、何回まで試行できるのか、そして後からエンジニアはどこで経路チェーンを確認できるのか、ということです。AI API の負荷分散とフェイルオーバー のプレイブックは、その経路レーンを設計するための補完的な内容です。
同期的に再試行する代わりにキューに入れるべきタイミング
ユーザーが即時応答を必要としない場合、プロバイダーのキャパシティが一時的に制約されている場合、またはリクエスト量がバッチワークフローに属する場合は、作業をキューに入れます。キューは失敗ではありません。AI API リトライ戦略が同期制限と競合しないようにするための方法です。
OpenAI のレート制限ガイドでは、同期リクエスト制限とバッチ作業を区別しており、即時性を必要としないユースケースは、同期リクエストのレート制限に影響を与えずにバッチ形式の実行を使用できると述べています。この同じ製品原則は 1 つのプロバイダーに限らず当てはまります。非緊急の作業は対話型トラフィックから切り離してください。
キューに適した候補には、次のようなものがあります。
- 一括エンリッチメント、要約、埋め込み、モデレーションレビュー、またはレポート生成。
- すでに非同期ステータスページや webhook を持っている、顧客に見えるジョブ。
- 鮮度が数分または数時間単位で測定されるバックフィルや移行。
- ユーザーの対話的なレイテンシ予算を超えるが、ジョブキューには適合する Retry-After のウィンドウ。
キューレコードには、元のリクエスト所有者、API キー、ルートポリシー、再試行回数、要求されたモデル、キュー投入時刻、次回試行時刻、予算所有者を保持する必要があります。そうしないと、キューに入れた再試行が見えないコストになってしまいます。
いつフェイルクローズにするか
継続するとセキュリティ、コンプライアンス、データ、予算、または製品リスクの曖昧さが生じる場合は、フェイルクローズにします。これは、AI API リトライ戦略の一部であり、信頼性エンジニアリングが静かなポリシー迂回に変わるのを防ぎます。
次のような場合はフェイルクローズにします。
- 無効または無効化された API キー、プロジェクト権限の失敗、IP 許可リストの失敗、予期しないアカウント所有権。
- 安全性ブロック、モデレーションブロック、ツール権限の失敗、データ境界エラー。
- 予算のスピルオーバーが事前承認されていない場合の、クォータまたは予算の枯渇。
- 変更なしで繰り返される不正なリクエスト。
- 品質、コスト、プライバシー、コンプライアンスのチェックを通過していないフォールバック経路。
- すでに部分的なコンテンツを配信しており、きれいに再実行できないストリーミング応答。
フェイルクローズは、敵対的なエラーを返すことを意味しません。システムが制御されたメッセージを返し、停止理由を記録し、必要に応じて所有者に通知し、隠れた経路変更を避けることを意味します。これは、静かなフォールバックが実質的に異なる回答を生みうる、顧客向け AI 機能において特に重要です。
本番チーム向けの再試行ポリシーテンプレート
このテンプレートを使って、ラダーをポリシーレコードに変換します。これは意図的に汎用的にしてあり、ゲートウェイ、アプリケーション、コンプライアンス規則に合わせて調整する必要があります。
{
"policy_id": "chat-prod-retry-v3",
"workflow": "customer-chat",
"environment": "production",
"idempotency": {
"requires_client_request_id": true,
"allow_replay_after_stream_started": false
},
"same_route_retry": {
"retryable_status_codes": [408, 429, 500, 502, 503, 504],
"max_attempts": 2,
"backoff": "exponential_with_jitter",
"max_elapsed_ms": 9000
},
"fallback": {
"enabled": true,
"allowed_reasons": ["primary_timeout", "provider_overload", "temporary_5xx"],
"blocked_reasons": ["auth_error", "invalid_request", "safety_block", "budget_exhausted"],
"allowed_models": ["approved-backup-chat-model"],
"requires_quality_eval": true,
"requires_cost_owner": true
},
"queue": {
"enabled_for": ["bulk_summary", "nightly_enrichment"],
"not_enabled_for": ["live_customer_chat"]
},
"fail_closed": {
"auth_errors": true,
"policy_errors": true,
"unapproved_fallback": true,
"quota_without_budget_owner": true
},
"logging": {
"record_attempt_chain": true,
"record_retry_after": true,
"record_requested_and_selected_route": true,
"content_logging_mode": "metadata_only"
}
}これは Flatkey API の契約ではありません。エンジニアリング、プロダクト、財務、セキュリティの各チーム向けのレビュー用テンプレートです。最も重要な項目は、正確な JSON 名ではなく、各回復パスに対して明示された停止条件です。
Flatkey ロールアウトチェックリスト
Flatkey または任意の AI ゲートウェイで AI API のリトライ戦略 をテストする際は、このチェックリストを使用してください:
- まずステージングで開始: 非本番キーを使って、OpenAI 互換クライアントの接続先を
https://router.flatkey.ai/v1に設定します。 - 1 つのワークフローを選ぶ: すべてのモデルを一度にテストするのではなく、チャット、要約、埋め込み、画像、または動画のいずれか 1 つのルートを選びます。
- リトライ予算を設定: 最大試行回数、最大経過時間、およびどのステータスまたはエラー分類がリトライ可能かを定義します。
- フォールバックの適格条件を定義: 出力品質は製品承認、コストは財務承認、データ分類はセキュリティ承認を必須にします。
- キューのトラフィックを分離: 可能な場合は、バッチジョブを対話型のユーザーリクエストから切り離します。
- ポリシー問題ではクローズで失敗: 認証、安全性、予算、またはリクエスト形状の失敗が、黙って別のルートへ流れ込まないようにします。
- ログを確認: ダッシュボードまたはエクスポートされたログに、要求されたルート、選択されたルート、試行チェーン、ステータス、使用量、コスト、所有者が表示されることを確認します。
- 支出をレビュー: AI API のクォータ管理 と AI API のチーム別コスト配賦 のプラクティスを使用し、リトライ復旧が予算上の想定外にならないようにします。
2026 年 6 月 18 日に確認したところ、公開されている Flatkey の価格ページには、23 のプロバイダーにまたがる 638 の AI モデルのサーバー生成モデル価格が表示されていました。これは日付付きのカタログ証拠としてのみ扱ってください。本番トラフィックの前に、ワークフローに対する正確なモデル行、エンドポイント種別、価格単位、提供状況、ダッシュボード項目を確認してください。
避けるべき一般的なミス
- すべての429を同じように再試行する: レート圧力、加速制限、予算枯渇には、それぞれ異なる対応が必要です。
- 無効なリクエストを再試行する: スキーマ、コンテキスト、未対応パラメータのエラーには、再試行ではなくリクエストの修正が必要です。
- evalsなしでフォールバックする: より安価なモデルや利用可能なモデルが、同じ顧客ワークフローに自動的に適しているとは限りません。
- ストリーミングの状態を無視する: 部分的な出力の後に再試行すると、重複した回答や矛盾する回答が発生する可能性があります。
- 試行ログを残さない: インシデントレビューには、最終的な成功だけでなく、完全なルートチェーンが必要です。
- 再試行で予算制御を回避させる: 再試行のたびに新しいリクエスト、新しいトークン数、そして多くの場合新しいコスト項目が発生します。
よくある質問
AI APIのリトライ戦略は、失敗したリクエストを何回再試行すべきですか？
対話型トラフィックでは、まず1回または2回の試行と、厳格な経過時間の予算から始めてください。バックグラウンドジョブでは、より長いバックオフとより多くの試行を使えます。適切な回数は、冪等性、ユーザー遅延、プロバイダーのガイダンス、クォータ、コスト、そしてフォールバックが承認されているかどうかによって決まります。
LLM APIのリトライでは、同じモデルを使うべきですか、それともフォールバックモデルを使うべきですか？
一時的な障害である可能性が高い場合は、同じモデルを再試行してください。同じ経路でのリトライ予算を使い切り、かつフォールバックが品質、コスト、ツール、プライバシー、コンプライアンスのチェックを通過している場合にのみ、フォールバックを使用してください。
モデルのフォールバックリトライは、いつブロックすべきですか？
認証失敗、権限失敗、無効なリクエスト、安全性またはポリシーによるブロック、承認なしの予算枯渇、そして異なるモデルによって製品の許容範囲を超えてユーザーに見える挙動が変わる可能性があるワークフローでは、フォールバックをブロックしてください。
リトライおよびフォールバックのインシデントでは、何をログに記録すべきですか？
親リクエストID、試行インデックス、要求された経路、選択された経路、利用可能な場合はプロバイダーのリクエストID、ステータスコード、エラークラス、Retry-Afterデータ、レイテンシー、トークン使用量、コスト、フォールバック判断理由、最終結果を記録してください。メタデータ優先のロギングが通常は適切なデフォルトです。
結論: リカバリを明示する
AI API リトライ戦略は補助関数ではなく、本番環境の制御です。一時的な失敗は小さな予算内で再試行します。フォールバックが承認されている場合にのみモデルを切り替えます。同期応答を必要としない作業はキューに入れます。セキュリティ、安全性、予算、またはリクエスト形式が真の問題である場合は、クローズドで失敗させます。
チームが1つのキー、互換性のあるベースURL、そしてモデルルーティング、価格設定、使用状況、リカバリ動作を確認するためのより明確な場所を求めているなら、Flatkey のキーを取得し、本番トラフィックの前にステージングでリトライの階段処理をテストしてください。
