Claude APIのサーバーサイドフォールバックを1リクエストで使う設定

Claude Fable 5.1 / Fable 5 / Opus 5は安全性の分類器を備えており、リクエストを拒否することがあります。この拒否(refusal)を別モデルへ自動で再試行させたいとき、最も手数が少ないのがサーバーサイドフォールバックです。1回のAPIコールの中でAnthropic側が再試行まで完結させるため、呼び出し側は拒否と成功を意識せずに1つのレスポンスを受け取れます。

拒否を検知して別モデルへ再試行するロジックは、これまで呼び出し側で自前に実装する必要がありました。サーバーサイドフォールバックを使うと、この再試行ロジックをAnthropic側に任せられるため、呼び出し側のコードは通常のAPIコールと同じ形のまま拒否への対応を組み込めます。複数のサービスから同じAPIを呼んでいる場合、再試行ロジックをサービスごとに重複実装せずに済む点が実務上の利点です。

サーバーサイドフォールバックは何を1リクエストにまとめるか

サーバーサイドフォールバックは、拒否されたリクエストを同じAPIコールの中で再試行する仕組みです。既定モードでは、主モデルが拒否し、その拒否カテゴリに推奨フォールバック先が設定されている場合、Anthropicがそのカテゴリ向けに推奨するモデルで同じリクエストを実行します。自分で最大3つまでフォールバックモデルを指定することもできます。どちらの方式でも、返るレスポンスは1つで、そこには実際に応答したモデル名が含まれるため、利用者は1往復で答えを受け取れます。

現在ベータ機能で、Claude APIでのみ使えます。Message Batches APIでは fallbacks パラメータ自体がサポートされず、含めたバッチ項目はエラー結果として返ります。Amazon Bedrock・Google Cloud・Microsoft Foundryでも利用できません。これらの環境ではクライアントサイドフォールバックのSDKミドルウェアを使います。

既定ルーティングでリクエストを送る

fallbacks パラメータを文字列 "default" に設定し、server-side-fallback-2026-07-01 ベータヘッダーを送ります。APIはリクエストしたモデルのサーバー定義済みデフォルトルーティングを適用し、分類器が報告した拒否カテゴリに基づいて推奨フォールバックモデルを選びます。

curl --fail-with-body -sS https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: server-side-fallback-2026-07-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-fable-5",
    "max_tokens": 1024,
    "fallbacks": "default",
    "messages": [{"role": "user", "content": "Hello, Claude"}]
  }' | jq -c '{stop_reason, model}'

このベータヘッダーは日付の指定が厳密です。2026-07-01 は "default" と明示リストの両方に対応し、2026-06-01 は明示リストのみに対応します。それ以外の server-side-fallback-* の値を指定すると400エラーになります。以前のプレビュー版のヘッダーで実装している場合は、日付とリクエスト/レスポンスの形状を本記事の内容に合わせて更新する必要があります。

Anthropicはモデルごと・方針カテゴリごとに個別のセーフガードを設定しており、カテゴリによってはより能力の低いモデルへフォールバックするか、拒否がそのまま維持されるかが変わります。"default" モードはこのモデル別・カテゴリ別の推奨をあらかじめエンコードしているため、推奨フォールバックが更新されても、呼び出し側でモデル一覧を保守する必要がありません。フォールバックが発生したかどうかは常に見えます。レスポンスの model フィールドに実際に応答したモデル名が入り、content の中に fallback ブロックが挿入されて引き継ぎの位置を示します。

運用側でモデルごとの安全性ポリシーを常時追跡する体制がない場合は、既定ルーティングを選ぶことで、その追跡作業自体を省略できます。反対に、フォールバック先が変わることで出力特性が変わると困るアプリケーションでは、次のセクションで扱う明示リストの方が向いています。

このルーティングはサーバー側で適用され、Models APIにモデルごとの対応表として公開されているわけではありません。どのモデルが拒否されたリクエストに応答したかを確認するには、レスポンスの model フィールドと usage.iterations 内の fallback_message エントリを見ます。

フォールバックが発火するのは安全性分類器による拒否だけです。リクエストしたモデルのレート制限・過負荷・サーバーエラーは、そのままの形で返されます。この境界はstop_reasonとエラーの違いで扱った「stop_reasonとHTTPエラーは別レイヤー」という設計の延長線上にあり、フォールバックの対象になるのは常にrefusal(stop_reason)側だけです。

自分でフォールバックモデルを指定する

既定ルーティングの代わりに、fallbacks に最大3つまでのモデルのリストを設定できます。リクエストしたモデルが拒否すると、APIは同じリクエストをチェーンの次のモデルで実行します。アプリケーションが検証済みのモデルに固定したいなど、どのモデルが拒否リクエストに応答するかを厳密に制御したいときに使います。

求められる出力形式が厳しく、フォールバック先のモデル特性を事前に検証済みのケースでは、明示リストの方が挙動を予測しやすくなります。反対に、フォールバック先の候補が頻繁に変わる開発初期の段階では、既定ルーティングの方が一覧の保守にかかる手間を抑えられます。どちらを選ぶかは、フォールバック先の挙動をどこまで厳密に管理したいかで決まります。

curl --fail-with-body -sS https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: server-side-fallback-2026-07-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-fable-5",
    "max_tokens": 1024,
    "fallbacks": [{"model": "claude-opus-4-8"}],
    "messages": [{"role": "user", "content": "Hello, Claude"}]
  }' | jq -r '.model'

fallbacks リストには次の規則が適用されます。

• エントリは順番に試されます。各エントリは他のエントリおよびリクエストしたモデル自身と異なる必要があります
• 各エントリはリクエストしたモデルの許可されたフォールバック先の1つでなければなりません。ベータヘッダーを設定した状態では、その一覧がModels APIのモデルエントリに allowed_fallback_models として公開されます
• 各エントリはモデル名を指定し、その試行限定で max_tokens / thinking / output_config / speed を上書きできます
• リクエストは指定したすべてのモデルへの直接リクエストとして有効でなければなりません。フォールバック先のモデルがリクエストの使う機能をサポートしない場合、APIは事前にリクエストを拒否します
• 既定モードと同様、フォールバックが発火するのは安全性分類器による拒否だけです
• フォールバックモデルがレート制限または過負荷の場合、フォールバックの試行自体が行われず、直前の拒否がそのまま返ります。この拒否の stop_details.recommended_model には、直接リトライすべきモデル名が入ります

想定するrefusal量に見合うレート制限をフォールバックモデル側に確保しておかないと、フォールバックが負荷時に拒否へ退化します。

使い分け早見表

レスポンスの読み方とストリーミングの挙動

レスポンスの形は通常のメッセージと同じで、2点が追加されます。トップレベルの model フィールドは、リクエストしたモデルかフォールバックかを問わず、実際に応答を生成したモデルを報告します。content 内の fallback ブロックは、あるモデルの出力から次のモデルへ切り替わった位置を {"type": "fallback", "from": {...}, "to": {...}} の形でマークします。

出力前に拒否が起きた場合、fallback ブロックが最初のコンテンツブロックになります。出力の途中で拒否が起きた場合(ストリーミングのみ)、開いていたコンテンツブロックが閉じられ、fallback ブロックが境界を示し、フォールバックモデルは部分出力の続きから生成します。非ストリーミングリクエストでは、途中拒否の挙動が変わります。レスポンスは拒否したモデルの部分出力を含まず、フォールバックモデルが最初から答え直す形になり、拒否前と同じ「先頭が fallback ブロック」というレスポンス形状になります。拒否された試行とその出力トークンは、いずれの場合も usage.iterations に記録されます。

会話を継続するときは、受け取ったアシスタントの内容をそのまま送り返します。ただし fallback ブロックより前の thinking / redacted_thinking / connector_text ブロックとクライアント側の tool_use ブロックは削除します。fallback ブロック自体と、それ以降のブロックはそのまま保持します。

課金とレート制限

出力を生成する前に拒否された試行は課金対象外です。トークン数は usage.iterations のエントリに記録されますが、課金はされません。出力を生成したすべての試行(途中で拒否されたものを含む)は、その試行を実行したモデルの単価で個別に課金されます。トップレベルの usage は、最終的に返されたメッセージを生成した試行の数値だけを表し、異なるモデルのトークンが1つのフィールドに合算されることはありません。実行されたすべての試行(拒否されたものを含む)は、そのモデル自身のレート制限を消費します。

拒否だけで終わった試行は課金されない一方、出力の途中まで進んでから拒否されたケースは、その試行で生成した分のトークンも課金対象になります。想定コストを見積もるときは、拒否が起きる比率だけでなく、拒否が出力前と出力途中のどちらで起きやすいかも合わせて考える必要があります。

サーバーサイドフォールバックと公式SDKミドルウェアは、どちらもfallback creditを自動適用するため、プロンプトキャッシュの書き直し分を二重に払う心配はありません。生のHTTPリクエストで自前のリトライを組む場合だけ、fallback creditを自分で扱う必要があります。プロンプトキャッシュはモデル単位で管理されているため、フォールバック先へ切り替わるたびにキャッシュがゼロから書き直しになる、という前提を踏まえた設計です。この仕組みの詳細はfallback_credit_tokenで二重課金を防ぐにまとめています。

まとめ

サーバーサイドフォールバックは、拒否されたリクエストを1回のAPIコールの中で別モデルに再試行させるベータ機能です。fallbacks: "default" なら運用側の保守なしにAnthropic推奨のフォールバック先へ切り替わり、明示リストならどのモデルが応答するかを固定できます。どちらのモードも安全性分類器の拒否だけに反応し、レート制限やサーバーエラーには影響しません。Message BatchesやAWS/GCP/Foundry環境では使えないため、その場合はクライアントサイドフォールバックのSDKミドルウェアで同じ目的を達成します。