メインコンテンツまでスキップ

サーバー側フォールバックとフォールバッククレジット

上級

Opus 5 以前、Claude の拒否は あなたの 問題でした。分類器が拒否すると、幸せそうな HTTP 200 の上に stop_reason: "refusal" が返ってきて、リトライはあなたの責任 — 別のモデルを選び、履歴全体を送り直し、新しいモデルには別のキャッシュ名前空間があるためプロンプトキャッシュが溶けるのを見つめ、同じ会話が二重請求される理由を経理チームに説明することになります。

Opus 5 のローンチ(2026年7月24日)では、これらすべてを 1回の API 呼び出しに集約する 2つの関連ベータ機能 が出荷されました:

  1. サーバー側フォールバック (server-side-fallback-2026-07-01) — fallbacks: "default" を設定すると、API は同じラウンドトリップ内で、拒否カテゴリに対して Anthropic が選択したモデルで拒否されたリクエストをリトライします。自分で最大3つのターゲットを指定することもできます。
  2. フォールバッククレジット (fallback-credit-2026-07-01) — すべての拒否に添付される一度きりのクレジットトークンで、リトライ時にエコーすると、会話が最初からフォールバックモデル上にあったかのようにリトライが再課金されます。新しいモデルでのキャッシュ書き込みがキャッシュ読み取りになります。

2つのベータは独立しています — すでにクライアント側のリトライロジックがあるならフォールバッククレジットだけを使うこともできますが、このリリースの主眼は、ほとんどの場合それが不要になることです。このページでは、コピペで済むワンライナーから本番を刺すコーナーケース(tool_use の途中でのストリーミング、スティッキールーティング、output_config.format が継続シェイプをロックアウトすること)まで、両方を順に解説します。

What you'll learn
  • ワイヤー上で拒否が実際にどのように見えるか(JSON、5つの停止カテゴリ、トークンが課金されるタイミング)
  • フォールバックの3つの方法(サーバー側 / SDK ミドルウェア / 手動生 HTTP)と、それぞれがいつ正解になるか
  • ワンライナー: fallbacks: 'default' とベータヘッダー、そしてレスポンスシェイプに何が追加されるか
  • 明示的リストとデフォルトモード、allowed_fallback_models、そしてなぜ順序が重要か
  • フォールバッククレジットがプロンプトキャッシュの二重支払いを止める仕組み — トークン、2つのリトライボディシェイプ、usage.iterations に何が表示されるべきか
  • すべての手動リトライが実装しなければならない3段階の拒絶ラダー(継続 → 変更なしボディ → トークン放棄)
  • 動作しない場所: Message Batches、Bedrock/GCP/Foundry のギャップ、Sonnet 5、tool_use 途中のストリーミング拒否、output_config.format + サーバーツール

★ Insight ───────────────────────────────────── ここで内在化すべき Anthropic 固有の指紋が2つあります。まず、分類器の拒否は stop_reason: "refusal" を伴う 200 です — 4xx ではありません。エラーハンドラが非 2xx を「リトライ」として扱うなら、拒否は静かに無視されます。200 を「成功」として扱うなら、空のコンテンツを静かに表示します。どちらも望むものではありません。次に、プロンプトキャッシュは モデルごと です。そのため、別の Claude モデルへの素直なリトライは、会話プレフィックスがバイト単位で同一でも、常にキャッシュ書き込みコストを最初から支払います。クレジットトークンはその穴を塞ぐピースであり、fallback-credit がサーバー側フォールバックとは別のベータとして存在する理由です。 ─────────────────────────────────────────────────

拒否が実際にどう見えるか​

分類器の拒否は、空の content 配列と stop_reason: "refusal" を持つ通常のメッセージレスポンスです:

{
  "id": "msg_01XFUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "model": "claude-fable-5",
  "content": [],
  "stop_reason": "refusal",
  "stop_details": {
    "type": "refusal",
    "category": "cyber",
    "explanation": "This request was declined because it could enable cyber harm."
  },
  "usage": {
    "input_tokens": 412,
    "output_tokens": 0
  }
}

stop_details.category は5つの値のいずれかです。2つは、拒否が名前付きカテゴリにマッピングされない場合 null になります(プレースホルダーではなく恒久的な null):

category何がトリガーしたか
"cyber"サイバー被害を可能にする可能性のあるリクエスト(マルウェア、エクスプロイト開発)。良性のサイバーセキュリティ作業でも発火することがあります。
"bio"生物学的被害を可能にする可能性のあるリクエスト。有益な生命科学の作業でも発火することがあります。
"frontier_llm"競合する AI モデルの開発を支援する可能性のあるリクエスト、Anthropic の商用条件により制限されています。
"reasoning_extraction"モデルに内部推論を応答テキストで再現するよう要求するリクエスト。構造化された形式で推論を取得するには 適応的思考 を使ってください。
"general_harms"その他の被害領域;良性の作業でも時折発火します。

出力前 に到着する拒否は課金されません(usage にトークンが表示されますが課金されません);レート制限にはカウントされます。ストリーム途中の拒否 は入力とすでにストリーミングされた出力を通常レートで課金します。いずれにせよ、部分的な出力は不完全とみなして破棄してください — 安全分類器はモデル自身の軌道で発火しました。

explanation 文字列はバージョン間で安定していません。表示してください、パースしないでください。

フォールバック方法を選ぶ​

3つの方式があります。自分に合う行を選んでください:

あなたの状況使うもの理由
Claude API、最もシンプルなものが欲しいサーバー側フォールバック with fallbacks: "default"1リクエスト、1レスポンス。API がフォールバックを選択し、クレジットを適用します。
任意のプラットフォーム(Bedrock、Vertex、Foundry)で Anthropic SDK 使用SDK ミドルウェア (BetaRefusalFallbackMiddleware)クライアントで一度設定。リトライ + クレジットは自動。Bedrock / Vertex / Foundry では今日これが唯一の道。
生 HTTP、カスタムリトライロジック、または非 Anthropic SDK手動リトライ with fallback-credit-2026-07-01 ヘッダー完全な制御。3段階ラダーを自分で実装。

サーバー側フォールバックと SDK ミドルウェアはフォールバッククレジットを自動的に適用します。リトライを自分で構築する場合にのみクレジットトークンダンスを考える必要があります。

ワンライナー: fallbacks: "default"​

機能全体を1リクエストで:

デフォルトモードでのサーバー側フォールバック

curl 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"}]
}'

Fable 5 が拒否し、拒否カテゴリに Anthropic 推奨のフォールバックがあれば、API は同じ呼び出しで同じリクエストをそのモデルで実行します。1つのレスポンスが返ってきて、トップレベルの model フィールドは実際に回答したモデルを示します。カテゴリに 推奨 フォールバックが ない 場合、拒否は残り、fallbacks を未設定にしたのと同じように拒否がそのまま返ってきます。

「default」が実際に行っていること: API はリクエストされたモデルのサーバー定義ルーティングテーブルを読み、拒否カテゴリに基づいてそこからフォールバックを選択します。Anthropic がそのテーブルを更新すると(カテゴリに新しいフォールバックを追加、Opus 5 を Fable 5 のデフォルトターゲットに昇格、など)、新しいルーティングを無料で手に入れられます。それが売り文句です: 1ヶ月後には間違いになるフォールバックモデルリストを保守するのをやめる。

ピン留めが必要な場合の明示的リスト​

自分でルーティングを制御したい場合は、"default" の代わりにリストを渡します。最大3エントリ、順に試されます:

response = client.beta.messages.create(
    model="claude-fable-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
    fallbacks=[
        {"model": "claude-opus-5"},        # try Opus 5 first
        {"model": "claude-opus-4-8"},      # then Opus 4.8
    ],
    betas=["server-side-fallback-2026-07-01"],
)

読まないとつまずくルール:

  • すべてのターゲットは、リクエストされたモデルに対して許可されたフォールバックでなければなりません。 許可されたターゲットのリストは、server-side-fallback-2026-07-01 ベータヘッダーが設定されているとき、Models API の各モデルエントリで allowed_fallback_models として公開されます。(Claude Fable 5 の場合、執筆時点でそのリストは claude-opus-4-8 と claude-opus-5 です。)
  • エントリは互いに、そしてリクエストされたモデルとも別のものでなければなりません。
  • 各エントリはそのアテンプトについてのみ max_tokens、thinking、output_config、および speed を上書きできます。これが「フォールバックでは低い効率で実行する」と言う方法で、メインリクエストに触れずに済みます。
  • リクエストは、指名されたすべてのモデルに対して直接リクエストとして有効でなければなりません。 フォールバックがリクエストの使用する機能をサポートしていない場合(例: フォールバックモデルが受け入れないベータ)、API はフォールバックアテンプトだけでなくリクエスト全体を事前に拒否します。
  • 分類器の拒否のみがフォールバックをトリガーします。 リクエストされたモデルでのレート制限、過負荷、およびサーバーエラーはそのまま返ってきます。

"default" モードは server-side-fallback-2026-07-01 の下でのみ動作します。明示的リスト形式は古い server-side-fallback-2026-06-01 ヘッダーの下でも動作します。

レスポンスに含まれるもの​

レスポンスは、2つの追加を伴う通常のメッセージです:

  • トップレベルの model フィールドは、返されたメッセージを生成したモデル(リクエストまたはフォールバック)を示します。
  • fallback コンテンツブロックは、あるモデルの出力が次のモデルに引き継がれる各ポイントをマークします: {"type": "fallback", "from": {"model": ...}, "to": {"model": ...}}。出力前の拒否では、このブロックが 最初の コンテンツブロックです。ストリーム途中のフォールバックでは、引き継ぎポイントに現れます。
  • usage.iterations はすべてのアテンプトを記録します。拒否したモデルは message エントリとして表示され(トークンは報告されますが課金されません)、ターンを提供したモデルは fallback_message エントリとして表示されます。

出力前の拒否の後、デフォルトルーティングが Opus 4.8 を選択した場合の例:

{
  "id": "msg_01XFUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "model": "claude-opus-4-8",
  "content": [
    { "type": "fallback", "from": { "model": "claude-fable-5" }, "to": { "model": "claude-opus-4-8" } },
    { "type": "text", "text": "Hi! How can I help you today?" }
  ],
  "stop_reason": "end_turn",
  "stop_details": null,
  "usage": {
    "input_tokens": 412,
    "output_tokens": 264,
    "iterations": [
      { "type": "message",          "model": "claude-fable-5",  "input_tokens": 535, "output_tokens": 0   },
      { "type": "fallback_message", "model": "claude-opus-4-8", "input_tokens": 412, "output_tokens": 264 }
    ]
  }
}

チェーンのすべてのモデルが拒否した場合、レスポンスは最後のモデルの拒否で、それより前のホップごとに message エントリが、最後のものに fallback_message エントリが付きます。

会話を継続する​

次のターンでは、受け取ったままアシスタントのコンテンツをエコーします。ミッド出力フォールバックの後、受け取った content には引き継ぎ前に拒否モデルが生成したブロックが含まれる場合があります。何を保持し何を落とすか:

ブロックタイプ次のターンで
fallback保持 して、そのままの位置に。位置は周囲の thinking ブロックの検証に使用されます。移動または削除 → 400。
text保持。
最後の fallback ブロックの 後 の任意のブロック保持。
最後の fallback の 前 の thinking、redacted_thinking、connector_text落とす。
最後の fallback の 前 のクライアント側 tool_use落とす。
最後の fallback の 前 の server_tool_use結果とペアの場合は保持。マッチする結果がない場合は落とす。

メンタルモデル: フォールバックモデルで実行されたすべては残り、拒否モデルの裏付けのない中間作業は消えます。

スティッキールーティング​

会話がフォールバックすると、API はそれを記憶します。その会話に関して fallbacks パラメータも含む後のリクエストは、リクエストされたモデルを完全にスキップして 直接 フォールバックモデルに行きます。これにより、常に拒否することが決まっていたセッションのすべてのフォローアップで拒否税を払うことを止めます。

知っておくべきプロパティ:

  • 約1時間保持、あなたの組織にスコープされます。
  • 会話プレフィックスのコンテンツハッシュ + それを提供したモデル として保存されます。メッセージのコンテンツ自体はサーバー側に保存されません。
  • ベストエフォート — コードはリクエストされたモデルがいつでも再試行されうる状況を処理しなければなりません。
  • スティッキー配信のターンには fallback コンテンツブロックがありません(そのターンには何も拒否しなかった)。usage.iterations に fallback_message があること、リクエストされたモデルの message エントリがないこと、およびレスポンスの model フィールドで識別します。

ストリーミングでは、ルーティング決定はストリームが開く前に行われるため、message_start はすでにフォールバックモデルの ID を運びます。

ストリーミングの動作​

リトライは 同じストリーム 上で発生します — すでに受け取ったものは無効化されません。

出力前の拒否

  • message_start はフォールバックモデルを指名します。
  • fallback ブロックが最初のコンテンツブロックです。
  • 最初のバイトまでの時間は拒否されたアテンプトを含みます(message_start はフォールバックの開始を待つため)。

出力途中の拒否

  • 現在開いているコンテンツブロックが閉じられます。
  • fallback ブロック(content_block_start + content_block_stop、デルタなし)が境界をマークします。
  • フォールバックモデルは部分出力から続行します。text ブロックのみ が部分出力からフォールバックモデルへのコンテキストとして渡されます。他のブロックタイプは content に残りますがフォールバックには見えません。
  • message_start はすでにリクエストされたモデルを指名しているので、提供するモデルは fallback ブロックの to.model および最終 message_delta の usage.iterations の fallback_message エントリから読んでください。

非ストリーミング、ミッド出力拒否: レスポンスは拒否モデルの部分出力を 省略 し、フォールバックはゼロから回答します。結果は出力前の拒否のように見えます — fallback ブロックが最初 — 拒否されたアテンプトのトークンは usage.iterations にまだ記録されます。これはストリーミングとの真の動作差であり、ストリームで行ったサイジングテストは、非ストリーミングに切り替えた際のコストを過小予測することがあります。

フォールバッククレジット: 目に見えない再課金​

プロンプトキャッシュはモデルごとです。Fable 5 があなたの会話プレフィックスの 400k トークンをキャッシュして拒否した場合、Opus 5 での素直なリトライは 400k すべてを Opus 5 のキャッシュに最初から書き込まなければなりません — そして キャッシュ書き込みはキャッシュ読み取りよりコストがかかります。フォールバッククレジットはそのエクストラコストを削除します。拒否は 一度きりのクレジットトークン を運び、リトライ時にトークンをエコーすると、リトライは会話が最初からフォールバックモデル上にあったかのように課金されます。

サーバー側フォールバックと SDK ミドルウェアはクレジットを自動的に適用します。生 HTTP でリトライを構築する場合にのみトークン自体を考える必要があります。

手動フローの4ステップ​

Guided walkthrough1 of 4
  1. 最初のリクエストを anthropic-beta: fallback-credit-2026-07-01 で送信します。(server-side-fallback-2026-07-01 は同じフィールドを付与し、古い fallback-credit-2026-06-01 ヘッダーもまだ受け入れられます。)

すべての手動リトライが必要とする拒絶ラダー​

ほとんどのリトライは最初のアテンプトで引き換えます。そうでない場合、API は次に何を試すべきかを教える 400 を返します。3つの段すべてを実装してください:

Guided walkthrough1 of 3
  1. 最も一般的な原因は、output_config.format またはツール使用を強制する tool_choice が継続シェイプを除外することです。追加されたアシスタントメッセージを落とし、トークンを維持します。
Watch out
  • 「redemption temporarily unavailable」は一時的なエラーであり、リトライシェイプに対する判決ではありません。5分ウィンドウ内で同じトークンで同じリクエストを再試行してください。ラダーを下がらないでください。

正確に一致しなければならないフィールド(厳格マッチルール)​

引き換えは、リトライを拒否されたリクエストと比較します。プロンプトを形作るすべてのフィールドは一致しなければなりません:

ルールフィールド
正確に一致system、messages、tools、tool_choice、thinking、cache_control、および(使用時)output_config、mcp_servers、context_management、container
リトライで変更可model、max_tokens、stop_sequences、temperature、top_p、top_k、stream、metadata、service_tier

継続シェイプは messages マッチの唯一の例外です: messages の末尾にアシスタントメッセージをちょうど1つ追加します。

2つの微妙なトラップ:

  1. ベータヘッダーも一致しなければなりません。 2つのリクエストの片方だけにあるベータヘッダーは、ボディが同一でもマッチを失敗させます。400 は request body ... does not match と言いますが、これはボディの差異のように読めますが実際にはヘッダーの差異です。2つのファミリーは免除されます: server-side-fallback-*(リトライで fallbacks パラメータとともに落とす)、および fallback-credit-*(両方に維持する)。
  2. リトライで前のターンの thinking または redacted_thinking ブロックを剥がさないでください、通常のトークンレスなリトライは通常剥がしますが。ボディは拒否リクエストと一致しなければなりません;サーバーはそれらのブロックを自分で処理します。

クレジットが実際に適用されたかを確認する​

返金はリトライの usage で確認できます。トークンなしで同じリクエストが報告するものと比較して、cache_creation_input_tokens は 低く、cache_read_input_tokens は 同じ量だけ高く なります。ゼロシフトはトークンが受け入れられたが再課金するものがなかったことを意味します(例: リトライモデルのキャッシュがすでに温まっていた)。

トークンのスコープと寿命​

  • 拒否を受け取った組織とワークスペースからのみ引き換え可能(Foundry でも)。ワークスペースがない Bedrock と Vertex では、トークンはプラットフォームの呼び出し元 ID にバインドされます。
  • 拒否から5分後に期限切れ。それ以降はトークンなしでリトライします。
  • ステートレス — サーバーは何も保存せず、検査や取り消しのエンドポイントはありません。

動作しない場所(または異なる動作をする場所)​

Guided walkthrough1 of 6
  1. fallbacks パラメータは Message Batches API でサポートされていません(それを含むバッチアイテムはエラー結果として返ってきます)。Message Batches での拒否はクレジットトークンを発行せず、バッチリクエストで渡されたトークンは受け入れられますが無視されます。バッチが解決した後にクライアント側のリトライにフォールバックしてください。

本番 Claude アプリのための実践的なセットアップ​

Guided walkthrough1 of 5
  1. Anthropic が推奨フォールバックを持つカテゴリに対するゼロエフォート保護。ルーティングテーブルが自動的に更新されるため、手動アプローチのスーパーセットです。

他のプロバイダーがすることとの比較​

プロバイダー1回の API 呼び出しでの自動拒否 → フォールバック?
Anthropic Claude Fable 5 / Opus 5はい — fallbacks: "default" + クレジットトークン。スティッキールーティングがフォローアップを運びます。
Anthropic Claude Opus 4.8クレジットトークンのみのバリアントのターゲットモデルでした(2026年6月ベータ)。サーバー側デフォルトモードは Opus 5 で登場。
OpenAI GPT-5 / 6ファーストパーティのサーバー側フォールバックなし。refusal finish_reason を自分で検出し、クライアント側で別のモデルにリトライします; Responses API は allowed_fallback_models の相当物を公開しません。
Google Gemini 3拒否は SAFETY ブロック理由として現れます; リトライはファミリー内の別のモデルに対してクライアント側で行います。
AI ゲートウェイ (LiteLLM、Portkey、OpenRouter)プロバイダー非依存のルーターレベルのフォールバックは存在しますが、各アテンプトで独立に課金されます — プロバイダーごとのキャッシュクレジット相当物はありません。AI ゲートウェイ を参照。

クロスモデルハーネスはまだクレジットトークンを使用できます: モデル固有ですが、コンセプト(リトライで不透明なトークンをエコーし、再課金される)はプロバイダーごとに機能検出できます。

一般的な失敗モードとその意味​

  • 空の content 配列が返ってきて UI が空白のメッセージを表示する。 レンダリング前に stop_reason: "refusal" をチェックし忘れました。検出して、カテゴリ固有のメッセージを表示するかフォールバックを配線してください。
  • リトライが request body ... does not match で 400 し続ける。 ヘッダーの不一致の可能性が最も高いです。ボディだけでなく、2つのリクエスト間のすべての anthropic-beta ヘッダーを差分してください。
  • SDK ミドルウェアを使用し、同じモデルが二重課金される。 同じ会話のリクエスト間で BetaFallbackState を共有し忘れました。スティッキールーティングはフォローアップをピン留めするために状態を必要とします。
  • Fable 5 にいるつもりだったのに、コストレポートが Opus 4.8 の大きなジャンプを示す。 拒否後、スティッキールーティングがフォローアップを運びました。ログで response.model と usage.iterations を見てスプリットを確認してください。
  • リトライでベータヘッダーを忘れて 引き換え失敗になりました。リトライはトークンを引き換えるために fallback-credit-2026-07-01 を必要とします。
  • バッチジョブがフォールバックを黙って落とす。 バッチは fallbacks とクレジットトークンを無視します。バッチ完了後にリトライしてください。
カードがまだありません — 追加して学習を始めましょう。🃏

Check yourself

0/7
  1. Claude Fable 5 のリクエストが HTTP 200 と `stop_reason: 'refusal'` および空のコンテンツ配列を返します。いくら課金されますか?
  2. `server-side-fallback-2026-07-01` ヘッダーで `fallbacks: 'default'` を Fable 5 リクエストに送り、カテゴリ `reasoning_extraction` で拒否されました。何が起こりますか?
  3. 拒否されたリクエストとクレジットトークンリトライ間で、どの Claude API フィールドが正確に一致しなければなりませんか?
  4. ミッド出力で発火した拒否で `stop_details.fallback_has_prefill_claim: true` を得ました。どのリトライボディを構築すべきですか?
  5. ストリーミング Fable 5 リクエストが、`tool_use` ブロックがストリームでまだ開いている間に拒否します。API は何をしますか?
  6. 1つの拒否ターンから数日後、Fable 5 に行くと思っていたターンで Opus 4.8 の課金がビリングに表示されます。何が起こっていますか?
  7. 強力なクライアント側リトライを構築しているので、サーバー側フォールバックを使用したくありません。それでもキャッシュクレジット節約を得られますか?

ソースと参考資料​