Skip to Content
ドキュメントアドバンスドフォールバック

フォールバック

provider.fallback には代替モデルを列挙します。主モデルが上流で失敗したとき、リストの順に試されます。

設定方法

fallback はモデル ID の配列を受け取り、type と同じ階層で provider の下に置きます。最大 3 モデルで、超えると 400 を返します。

Terminal
curl https://api.ofox.run/v1/chat/completions \
  -H "Authorization: Bearer $OFOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-5",
    "messages": [{ "role": "user", "content": "..." }],
    "extra_body": {
      "provider": {
        "fallback": ["openai/gpt-5.5", "google/gemini-2.5-pro"]
      }
    }
  }'

公式の OpenAI SDK を使用する場合、extra_body はリクエストボディのリテラルなキーとして存在する必要があります。TypeScript SDK はパラメータオブジェクトに記述したとおりに送信します。Python SDK の extra_body= 引数は内容をボディのトップレベルにマージするため、キーをもう 1 段階深くネストするか、リクエストヘッダーで渡してください。

フォールバックが発動する条件

フォールバックが覆うのは、ルーティングがチャネルを選んだ後に起きた失敗だけです：

状況挙動
上流プロバイダーがエラーを返すフォールバックする —— リストのモデルを順に試し、最初に成功したレスポンスを返します
ルーティング時点の失敗（モデルが存在しない、指定したプロバイダーがそのモデルを提供していない）フォールバックしない —— リクエストはその場で終了します

2 行目ははっきり書いておく価値があります：そのモデルを提供していないプロバイダーを provider.type で指定すると 400 provider_type_unavailable、存在しないモデルを指定すると 404 model_not_found が返り、どちらも fallback リストには到達しません。どの上流エラーがフォールバックを発動させるかは、固定のリストではなくゲートウェイの実際の挙動に従います。

プロバイダー指定との組み合わせ

fallback と type は同時に送れます。type は主モデルがどのプロバイダーで動くかを制約し、fallback は主モデルが失敗したあとを担当します：

{
  "model": "anthropic/claude-sonnet-5",
  "messages": [{ "role": "user", "content": "..." }],
  "extra_body": {
    "provider": {
      "type": "bedrock",
      "fallback": ["openai/gpt-5.5"]
    }
  }
}

フィールドの詳細は プロバイダールーティング を参照してください。

よくあるエラー

error.type発生条件
invalid_request_errorfallback リストのモデルが 3 個を超えています。

ベストプラクティス

  1. 能力の近い代替モデルを選ぶ —— フォールバック後も出力品質を揃えるため。
  2. ベンダーをまたいで選ぶ —— 同一ベンダーのモデルは同時に使えなくなりがちです。
  3. 発動頻度を監視する —— 頻繁に発動するなら主モデルを見直すべきサインです。
Last updated on
プロバイダールーティングプロンプトキャッシュ