信頼性 early stream errors API 運用

プロバイダー障害時の LLM API フェイルオーバー戦略

プロバイダー障害時の LLM API フェイルオーバー戦略の実践ガイド。early stream errors、configured retry status、transient body messages、本番判断、結果確認を扱います。

AveMujica API 2026年6月22日 2 分で読めます

LLM API フェイルオーバーとは、主なプロバイダーがエラーを返した場合、タイムアウトした場合、またはストリーム途中でトークン生成を停止した場合に、生成 AI リクエストを代替プロバイダーに振り分ける運用手法です。本番環境に耐える戦略は、単に「動くまで再試行する」というものではありません。安全に再試行できるエラーと、即座に失敗すべきエラーを区別し、ストリームの初期に発生した失敗と、ユーザーに部分的な出力を送信した後に発生した失敗を異なる扱いにする必要があります。

フェイルオーバーが見た目ほど単純でない理由

多くの API ゲートウェイは、HTTP のリクエスト/レスポンスというセマンティクスを中心に構築されています。5xx ステータスは通常、「別のプロバイダーで再試行しろ」を意味します。しかし、LLM ワークロードにはこの前提を崩す 2 つの複雑さがあります。

第一に、多くのリクエストがストリーミングされます。HTTP ステータスが 200 であっても、プロバイダーはアシスタントが発話を開始した後にエラーチャンクを返すことがあります。一度トークンがクライアントに届いてしまうと、単純な再試行は部分的な回答を繰り返し、ユーザーを混乱させ、すでに消費したトークンを二重に課金してしまいます。

第二に、同じ症状がまったく逆の原因を持つことがあります。429 Too Many Requests は数秒で解消することが多い一方、401 Unauthorized や 403 Forbidden は認証情報がローテーションされるまで持続します。後者を再試行すると、コストとレイテンシーの両方の予算を無駄にします。

このため、OWASP Top 10 for LLM Applications 2025 は、過度な自律性（excessive agency）と制御されていない再試行をアーキテクチャリスクとして扱っています。自動化されたループはコストを増幅させ、バックアッププロバイダーにデータを漏洩させ、データ居住地を侵害する可能性があります。

再試行する前に失敗を分類する

フェイルオーバーを安全に保つ最も信頼できる方法は、まず失敗を分類することです。プロバイダーの HTTP ステータス、ストリーム内の位置、エラーボディの構造を使用します。

ストリーム初期の失敗

これは、意味のあるトークンが生成される前に発生します。ゲートウェイは呼び出し元に出力をコミットしていないため、再試行やプロバイダーの切り替えは通常安全です。

一般的な例：

最初のトークン前の 408 Request Timeout
レート制限による 429 Too Many Requests
502 Bad Gateway、503 Service Unavailable、504 Gateway Timeout
レスポンスヘッダー完了前の TLS ハンドシェイク失敗や接続リセット

これらに対しては、指数関数的バックオフで再試行し、その後次に設定されたモデルにフェイルオーバーします。総レイテンシーをアプリケーションの許容範囲内に保ってください。30 秒もの再試行ループは、応答性の高いチャットインターフェースの目的を損ないます。

ストリーム途中の失敗

これは、少なくとも 1 つのコンテンツチャンクが配信された後に発生します。ユーザーは回答の一部を既に見ている可能性があるため、ゲートウェイは同じリクエストを透過的に再試行すると、重複または矛盾した出力のリスクを伴います。

推奨される対処：

クライアントへのストリームをきれいに停止する。
部分的なトークン数とともに、使用ログに失敗を記録する。
モデルを暗黙的に切り替えるのではなく、呼び出し元または UI にエラーを通知する。
ユーザーが明示的に再生成できるようにする。UI はその次のリクエストをフォールバックプロバイダーに振り分けることができます。

一部のチームは、部分的なアシスタントメッセージをコンテキストとして返送し、フォールバックに続きを書かせる「切り詰めからの継続」を実装しています。これは、2 つのモデルが同じトークナイザー動作を共有し、トーンや書式の変化を許容できる場合にのみ機能します。デフォルトで安全な動作ではありません。

通常は再試行すべきでないステータスコード

ステータス	典型的な意味	再試行？
`400 Bad Request`	ペイロードの形式不良、無効なパラメータ、またはセーフティフィルタの発動	いいえ — リクエストを修正する
`401 Unauthorized`	API キーが無効または期限切れ	いいえ — まず認証情報をローテーションする
`403 Forbidden`	アカウント停止、リージョンブロック、またはポリシー違反	いいえ — アカウントを調査する
`404 Not Found`	モデルまたはエンドポイントが存在しない	いいえ — モデルマッピングを更新する
`422 Unprocessable Entity`	リクエストボディの意味エラー	いいえ — ペイロードを修正する
`429 Too Many Requests`	レート制限またはクォータ枯渇	はい、バックオフ後にフェイルオーバー
`5xx`	プロバイダー側エラー	はい、限定再試行後にフェイルオーバー

この表は出発点であり、保証ではありません。プロバイダーは異なる失敗モードに同じステータスコードを再利用することがあるため、エラーボディが利用可能な場合は解析してください。

一過性のボディエラーの読み方

ステータスコードだけでは不十分です。OpenAI 形式のストリームは、rate_limit_exceeded、server_error、content_filter などの code フィールドを含む error チャンクを返すことがあります。Anthropic や Gemini は、理由文字列を含む構造化されたエラーオブジェクトを返します。これらのコードは、HTTP ステータスだけよりも再試行ポリシーを支配するべきです。

例えば：

rate_limit_exceeded → バックオフを入れて再試行し、その後フェイルオーバー。
server_error → 迅速にフェイルオーバー。プロバイダーが内部問題を認めています。
content_filter または content_policy_violation → ガバナンスポリシーが明示的に許可しない限り、別のプロバイダーで再試行しないでください。同じプロンプトが別の場所でも同じフィルタを発動させ、コンプライアンスリスクを生じさせる可能性があります。
insufficient_quota または billing_hard_limit_reached → 即座にフェイルオーバー。そのアカウントではこのリクエストを処理できません。

ボディエラーがストリーム途中で現れた場合、ステータスが 200 であってもストリーム途中の失敗として扱ってください。最も安全な方針は、ストリームを停止し、イベントをログに記録し、ユーザーが再生成するかどうかを判断させることです。

再試行予算とプロバイダー rotation

再試行ポリシーには上限が必要です。上限がなければ、あるプロバイダーの連鎖的障害が次のプロバイダーのレート制限を枯渇させる可能性があります。リクエストごとまたはセッションごとに以下を定義してください。

プロバイダーあたりの最大試行回数：通常、切り替え前に 1〜2 回の再試行。
試行するプロバイダーの最大数：通常、プライマリを含めて 2〜3 社。
バックオフの上限：ユーザーが諦める前にフェイルオーバーが完了するよう、指数関数的バックオフに上限を設ける。チャットインターフェースでは、一般的な上限は 2〜4 秒。
総タイムアウト：接続時間、初トークンまでの時間、トークン間レイテンシーを含める。

プロバイダーの rotation は、コスト構造の rotation も意味します。GPT-4o から Claude 3.5 Sonnet や Gemini 1.5 Pro へのフォールバックは、価格と品質の両方を変える可能性があります。ガバナンスの一環としてモデル価格の可視化を利用しているチームは、コストガードレールを設定でき、フェイルオーバーが推論請求を暗黙のうちに 3 倍にしないようにできます。

ロギングと可観測性

すべてのフェイルオーバーイベントは監査証跡を残すべきです。少なくとも以下を記録してください。

元のプロバイダーとフォールバック先プロバイダー
ステータスコードとボディ内のエラーコード
失敗がストリーム初期か途中か
既に消費されたトークン数（ある場合）
試行ごとのレイテンシーと総レイテンシー
ユーザーまたはプロジェクトの帰属

このデータは使用ログに存在し、ダッシュボードアラートの入力になります。あるプロバイダーが 5xx 率を上昇させ始めた場合、運用チームはユーザーがチケットを起票する前に気づくべきです。

ロギングは、課金紛争からも保護します。プロバイダーがストリーム途中のエラー前に出力したトークンを課金する場合、ストリームがいつ破断し、どれだけのトークンが関与したかを正確に記録する必要があります。

フェイルオーバーすべきでない場合

リクエストを別のプロバイダーに振り分けるのではなく、失敗させた方が合理的な場合もあります。

データ居住地とコンプライアンス。 プロンプトに個人データが含まれる場合、または特定の司法管轄区に準拠する必要がある場合、別の地域のプロバイダーへのフェイルオーバーはポリシー違反になる可能性があります。このようなプロンプトは制限されたチャンネルリストを通じてルーティングしてください。

コスト管理。 高級モデルに送信された高複雑度のプロンプトには、コスト的に同等のフォールバックが存在しない場合があります。安価なモデルにフェイルオーバーすると、結果が悪化するだけでなく、コンテキストウィンドウが大きい場合には想定以上のコストがかかることもあります。

コンテンツセーフティ。 プロバイダー A のセーフティフィルタで拒否されたプロンプトを、フィルタを迂回するために自動的にプロバイダー B で再試行すべきではありません。このパターンは責任リスクを生み、多くの許容使用ポリシーに違反します。

決定論的ワークロード。 コード生成、法務文書作成、医療支援ワークフローでは、特定のモデルバージョンが必要な場合があります。フェイルオーバーは出力分布を変え、下流の検証を無効にする可能性があります。

運用モデル：シンプルなランブック

LLM API フェイルオーバー戦略を設計またはレビューする際には、以下のチェックリストを使用してください。

各サポートモデルを、互換性のあるコンテキストウィンドウと出力形式を持つ 1 つ以上のフォールバックモデルにマッピングする。
プロバイダーごとに再試行回数、バックオフ、総タイムアウトを設定する。
コードとログの両方で、ストリーム初期の再試行とストリーム途中の失敗を区別する。
プロバイダー固有のエラーコードを解析し、必要に応じて HTTP ステータスベースのルールを上書きする。
プロジェクトまたは API キーごとにコストとレート制限の予算を設定する。
機微なデータの司法管轄区に対するフェイルオーバールートを制限する。
運用ダッシュボードを通じて、フェイルオーバー率の急増にアラートを出す。
どのエラーが自動再試行、フェイルオーバー、手動レビューを引き起こすかを文書化する。

総合

設計の良いフェイルオーバー戦略は、ゲートウェイを単なるプロキシではなく制御プレーンとして扱います。一時的な小障害と硬直した障害の違いを理解し、ユーザーが一貫した出力を見る権利を尊重し、コストを予測可能に保ちます。ステータスコードルール、ボディエラー解析、再試行予算、明確なロギングを組み合わせることで、チームはプロバイダーの障害を暴走する請求に変えずに AI 機能の可用性を維持できます。

複数のプロバイダーを単一のインターフェースの背後に統合している場合、より広い文脈も重要です。フェイルオーバーは、回復力のある AI アクセス層の一部に過ぎません。他には多くの AI モデル向けの 1 つの API、AI チーム向け API キー管理、モデル価格の可視化が含まれます。各機能は他を補強します：ガバナンスが誰がどこにルーティングできるかを定義し、価格の可視化が予期せぬコストを防ぎ、フェイルオーバーが単一プロバイダーがつまずいたときにシステムを立たせ続けます。

最終確認日：2026-06-22

AveMujica API が役立つ場面

AI ワークロードが実運用に入ると、課題は「呼び出せるか」から「誰が使い、いくらかかり、失敗時にどう扱うか」へ移ります。AveMujica API はモデルアクセス、価格文脈、ウォレット影響、利用履歴を同じコンソールにまとめます。

まず 1 つの実ワークフローで試します。
モデルアクセス、コスト、ログを同じ場所で確認します。
レイテンシ、支出、所有者が明確になってから対象を広げます。

ゲートウェイは手順を増やすためではなく、キー、請求、プロバイダー制限、障害対応を分散させないために使います。

参考資料

以下の一次情報で、プロバイダーの挙動、価格、リスク整理を確認できます。

よくある質問