Retries & Fallback

PleumRouter はプロバイダー呼び出しの失敗をエラー種別で分類し、リトライする価値のある失敗だけを 同じプロバイダーで再試行し、それ以外は直ちに次のプロバイダーへフォールバックします。複数 プロバイダーが提供するモデルでは、候補を価格順（または個人のルーティング設定順)に巡回するため、 1 つのプロバイダー障害がリクエスト失敗につながりません。すべて自動で、リクエストに何も追加する 必要はありません。

失敗の分類ルール#

失敗した試行は次のルールで分類されます。

429（レート制限） — 同じプロバイダーでリトライしますが、レスポンスの Retry-After ヘッダー（整数秒・HTTP 日付の両形式に対応）を尊重して 待機します。待機時間は最大 10 秒にキャップされ、ヘッダーがなければ指数バックオフを使います。

5xx・ネットワークエラー・不正な 200 レスポンス — 一時的な障害とみなし、同じ プロバイダーでリトライします。待機は指数バックオフ（0.5 秒から倍々）に ±10% のジッターを加え、 リトライの同時集中を緩和します。

401 / 403 — キーの問題であり、同じプロバイダーでのリトライは無意味なため、 待機せず直ちに次のプロバイダーへ進みます。

その他の 4xx（400・404・422 など） — リクエスト自体の問題である可能性が高いため 同じプロバイダーではリトライせず、次のプロバイダーで 1 回試行します（プロバイダーごとの パラメータ方言の違いで成功することがあります）。

リトライ回数：単一プロバイダーのモデルはデフォルトで 2 回リトライ（計 3 回試行）、マルチ プロバイダーのモデルはデフォルトでは同一プロバイダーのリトライなしで次の候補へ直行します。 プロバイダーの切り替えは待機なしで即時に行われます。これらの値は運用側で調整可能です。

フォールバックが起きた場合、レスポンスの provider フィールドが実際に サービングしたプロバイダーを示し、課金もそのプロバイダーの単価が基準になります（候補ごとに 単価が異なることがあります）。

{
  "id": "req-8f3a...",
  "model": "gpt-4o",
  "provider": "openai",
  "choices": [{"message": {"role": "assistant", "content": "..."}}],
  "usage": {"prompt_tokens": 120, "completion_tokens": 48}
}

ストリーミングのフォールバック#

ストリーミングでは、最初のデルタ（トークン）が送出される前の失敗だけが次の プロバイダーへシームレスにフォールバックします。同一プロバイダーへの再接続リトライも、デルタが 0 個の間にのみ行われます。