fallbacks parameter

通常は、同じリクエストを別の Claude モデルに送ると回答を得られます。fallbacks parameter (拒否時フォールバック) は、拒否されたリクエストを 1 回の API 呼び出しの中で別のモデルに再実行させる仕組みです。拒否が返る可能性のあるリクエストを扱うアプリケーションの設計に関わります。

安全分類器がリクエストを拒否した場合、レスポンスはエラーではなく通常の形で返り、stop_reason が "refusal" になります。Server-side fallback (サーバーサイドフォールバック) は、こうして拒否されたリクエストを 1 回の API 呼び出しの中で再実行します。

再実行のきっかけになるのは安全分類器による拒否だけです。要求したモデルで発生したレート制限・過負荷・サーバーエラーは、そのまま返ります。また、リストで指定したフォールバック先のモデルがレート制限や過負荷の状態にある場合、その試行は行われず、直前の拒否が返ります。

Claude Haiku 5.5 には Server-side fallback がありません。fallbacks: "default" を指定しても拒否は拒否のまま返り、フォールバック先モデルのリストを指定すると 400 エラーが返ります。

fallbacks パラメーターはオプトインで、Claude API と Claude Platform on AWS でベータとして提供されています。Message Batches API ではサポートされません。対象プランは公式のリリースノートには記載がありません。

• レスポンス最上位の model フィールドは、要求したモデルかフォールバック先かにかかわらず、返されたメッセージを生成したモデルを示します。
• content の中では、fallback コンテンツブロックが、あるモデルの出力から次のモデルの出力に切り替わる位置を示します。
• usage.iterations 配列にはすべての試行が記録されます。拒否したモデルは通常の message エントリー、応答したモデルは fallback_message エントリーとして現れます。
• ストリーミングのリクエストでは、再実行は同じストリーム上で行われ、受信済みの内容は無効になりません。出力の途中で拒否された場合、フォールバック先モデルは途中までの出力から続けます。
• ストリーミングでないリクエストで出力の途中に拒否された場合、レスポンスには拒否したモデルの途中までの出力が含まれず、フォールバック先モデルはその出力を文脈として使わずに回答します。

Sticky routing (スティッキールーティング) により、フォールバックが起きた会話の以降のリクエストで fallbacks を含めると、要求したモデルを実行せずに直接そのフォールバック先モデルへ送られます。この判断は約 1 時間保持され、組織の範囲で適用されます。

サーバー側の仕組みとは別に、SDK の refusal-fallback ミドルウェアを使うクライアント側のフォールバックもあります。

• BetaRefusalFallbackMiddleware (TypeScript では betaRefusalFallbackMiddleware()、Go では betafallback.BetaRefusalFallbackMiddleware()、C# では BetaRefusalFallbackHandler、Java では BetaRefusalFallbackInterceptor、PHP では RefusalFallbackMiddleware) をクライアントのコンストラクターに渡し、1 つの会話のリクエスト間で 1 つの BetaFallbackState インスタンスを共有します。
• 設定後は、client.beta.messages を通した呼び出しで、拒否されたリクエストがプラットフォームを問わず自動で再実行されます。
• ミドルウェアは、処理するすべてのリクエストに fallback-credit-2026-07-01 ベータヘッダーを付けます。
• リストのすべてのモデルが拒否した場合、エラーを発生させずに最後の拒否レスポンスを返します。
• 受け入れたモデルは BetaFallbackState に記録され、同じ状態を共有する後続のリクエストはそのモデルに固定されます。
• ミドルウェアとサーバー側の fallbacks パラメーターは、同じリクエストで両方を設定せず、どちらか一方だけを使います。

自分で再実行を書く場合は、レスポンスに stop_reason: "refusal" があるかを確認し、model をフォールバック先モデル (例: Claude Opus 4.8) にした同じリクエストを送ります。複数ターンの会話では、元のモデルに戻さず、以降のターンもフォールバック先モデルを使い続けます。

fallbacks パラメーターは Message Batches API ではサポートされないため、バッチでは次の流れで扱います。

1. バッチの結果から拒否された項目を集めます。
2. 複数ターンの履歴に含まれる thinking ブロックは、そのまま残すか、入力トークンを節約するために取り除きます。
3. 拒否された項目が thinking: {"type": "between_tools"} を送っていた場合は、thinking を省くか、フォールバック先モデルが受け付ける値にします。
4. 拒否された項目を、フォールバック先モデルで新しいバッチまたは直接のリクエストとして再送信します。

fallbacks パラメーターはベータとして提供されており、"default" モードの利用には server-side-fallback-2026-07-01 ベータヘッダーが必要です。

1. リクエストで fallbacks パラメーターに文字列 "default" を設定し、server-side-fallback-2026-07-01 ベータヘッダーを付けて送信します。
2. 拒否されたリクエストにどのモデルが応答したかを確かめるには、レスポンス最上位の model フィールドを確認し、usage.iterations に fallback_message エントリーがあるかを見ます。