ToRouterドキュメントトラブルシューティング
上流プロバイダエラーとフェイルオーバー
上流プロバイダに問題が起きたとき ToRouter がどのようにチャネルをまたいでリトライするか、そして救えないケースで何が見えるか。
ToRouter は各プロバイダの複数の上流アカウントの前段に位置します。あるチャネルが一時的に失敗すると、ゲートウェイは次の利用可能チャネルを自動的に試します。5xx が返るのは すべての 候補が失敗したときだけです。
自動フェイルオーバーのトリガー
ゲートウェイは上流が以下を返した場合、別のチャネルで再試行します：
429— 上流側でレートリミット超過401/402/403— 上流キーが失効、停止、またはクレジット切れ5xx— 上流のサーバーエラーまたは過負荷- レスポンスの最初のバイトが届く前の一時的ネットワークエラー
リトライされない もの（即座にあなたに返るもの）：
400— リクエストが不正。別チャネルでも同様に拒否される404— 上流にモデルがない。同様- ストリーミングレスポンスの最初のバイトがクライアントに届いた後のあらゆるエラー
ストリーミングリクエストでは、フェイルオーバーは 最初のバイトがクライアントに書き込まれる前 にしか機能しません。ストリームの途中で上流に切断された場合は、リトライではなく切り詰められたストリームとして見えます — 2 つのプロバイダの部分出力を安全につなぎ合わせる方法はありません。
フェイルオーバーが諦めたときに見えるもの
{
"error": {
"type": "upstream_unavailable",
"message": "Service temporarily unavailable"
}
}通常は 502 または 503 です。これはグループのローテーションに含まれるすべてのチャネルがエラーになったか除外された（レートリミット中、直近の失敗によるクールダウン中など）ことを意味します。
対処：
- バックオフ付きでリトライ — 一時的な上流の問題は数秒から数分で解消します。
- 利用状況ダッシュボード または 利用状況の詳細 で失敗リクエストの割合とステータスコードを確認します。特定プロバイダが広範に劣化（例：OpenAI のリージョン障害）していれば、公式ステータスページやニュースでも分かることが多いです。
- 別モデルを試す —
gpt-5が全面ダウンでも、同じグループのclaude-opus-4-7や Qwen 系モデルは動くかもしれません。
確定的な上流エラー（フェイルオーバーなし）
一部の上流エラーはリトライしても無意味なので、そのまま透過します：
| 上流が返す | あなたが見る | 理由 |
|---|---|---|
400 invalid_request_error | 元のメッセージ付き 400 | リクエストボディが不正 |
404 model_not_found | 404 | モデル slug がどの上流でも有効でない |
413 payload_too_large | 413 | プロンプトまたは添付ファイルが大きすぎる |
415 unsupported_media_type | 415 | 画像/音声フォーマット非対応 |
これらは リクエストを変更する ことを意味します。リトライではありません。
散発的な 5xx の切り分け
プロバイダが健全でも時々 502/503 が出る場合、特定の上流アカウントが劣化しているか、レートリミットやクールダウンに触れている可能性があります。利用状況の詳細 でモデル、チャネル、エラー列を突き合わせてください。