拒否とフォールバック

Claude Fable 5.1、Claude Fable 5、およびClaude Opus 5には、リクエストを拒否できる安全性分類器が含まれています。拒否が発生した場合、エラーではなく、stop_reason: "refusal"を持つ通常のレスポンスを受け取ります。そのstop_details.categoryはポリシー領域を示します（拒否の形式を参照）。通常は、同じリクエストを別のClaudeモデルに送信することで回答を得ることができます。このページでは、拒否を認識する方法と、その再試行を設定する方法を説明します。

これらのモデルのいずれかを基盤に構築していて、拒否されたリクエストを自動的に別のモデルへフォールスルーさせたい場合に、このページをお読みください。また、レスポンスで"refusal"を目にして、次に何をすべきか知りたい場合にも当てはまります。

関連ページ：

• 停止理由とフォールバック：stop_reasonの値の完全なリスト。
• フォールバッククレジット：再試行を自分で構築する際に、プロンプトキャッシュのコストを二重に支払うことを避ける方法。
• SDKミドルウェア：これらすべてをラップするSDKヘルパー。
• フォールバックと課金のクックブック：エンドツーエンドの実例。

最もシンプルな設定（Claude APIでベータ版）：fallbacksを"default"に設定すると、APIは拒否されたリクエストを、その拒否カテゴリに対してAnthropicが推奨するフォールバックモデルで再試行します。推奨フォールバックのないカテゴリでは、拒否はそのまま維持されます。

client = Anthropic()

response = client.beta.messages.create(
    model="claude-fable-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
    fallbacks="default",
    betas=["server-side-fallback-2026-07-01"],
)
print(response.model)

以下のセクションでは、拒否レスポンスに含まれる内容、サーバーサイドまたはクライアントサイドのフォールバックをいつ使用するか、そしてそれぞれがどのように課金されるかについて説明します。

拒否の形式

拒否は、stop_reason: "refusal"を持つ成功したHTTP 200レスポンスです：

{
  "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： 分類器をトリガーしたポリシー領域を示します。
• explanation： 人間が読める説明です。テキストは安定していないため、解析するのではなく表示してください。
• recommended_model： fallbacksを設定したリクエスト（サーバーサイドフォールバック、ベータ版）にのみ存在します。APIがフォールバック試行をスキップした場合（例えば、フォールバックモデルがレート制限されていた場合）に直接再試行すべきモデルを示し、それ以外の場合はnullです。これはヒントであり、保証ではありません。
• 拒否が名前付きカテゴリにマッピングされない場合、categoryとexplanationはどちらもnullになります。このnullは通常の恒久的な値であり、プレースホルダーではありません。
• refusal以外のすべての停止理由では、stop_details自体がnullです。

拒否は、出力が一切ない段階で届くこともあれば、部分的な出力の後にストリームの途中で届くこともあります。いずれの場合も、部分的な出力は不完全なものとして扱い、破棄してください。

フォールバック方式の選択

拒否されたリクエストを別のモデルで再試行する方法は3つあります。どれが適切かは、実行環境と必要な制御の度合いによって異なります。

サーバーサイドフォールバックとSDKミドルウェアは、フォールバッククレジットを自動的に適用します。フォールバッククレジットのページが必要になるのは、再試行を自分で構築する場合のみです。

サーバーサイドフォールバック

サーバーサイドフォールバックは、拒否されたリクエストを単一のAPI呼び出し内で再試行します。デフォルトモードでは、プライマリモデルが拒否し、その拒否カテゴリに推奨フォールバックがある場合、APIはそのカテゴリに対してAnthropicが推奨するモデルで同じリクエストを実行します。代わりに、独自のフォールバックモデルを最大3つ指定することもできます。いずれの場合も、回答したモデルを示す1つのレスポンスが返されるため、ユーザーは1回のラウンドトリップで回答を得られます。

リクエストの作成

fallbacksパラメータを文字列"default"に設定し、server-side-fallback-2026-07-01ベータヘッダーを送信します。するとAPIは、リクエストされたモデルのサーバー定義のデフォルトルーティングを適用します。このルーティングは、分類器が報告する拒否カテゴリに基づいて推奨フォールバックモデルを選択するため、推奨が変わってもモデルリストを自分で管理することなく、拒否されたリクエストが処理されます。

デフォルトルーティングは、選択していないモデルについて事前のサイズ超過画像の拒否を引き起こすことはありません。"oversized_image": "error"とマークされた画像をリサイズすることになるルーティング先モデルは、代わりにルーティングから除外されるため、マークされた画像がリサイズされて処理されることはありません。

client = Anthropic()

response = client.beta.messages.create(
    model="claude-fable-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
    fallbacks="default",
    betas=["server-side-fallback-2026-07-01"],
)

# usage.iterations に fallback_message エントリがあれば、フォールバックモデルが実行されたことを意味します。
# stop_reason と照合して、フォールバックがレスポンスを返したことを確認します。
fallback_ran = any(
    iteration.type == "fallback_message"
    for iteration in response.usage.iterations or []
)
served_by_fallback = fallback_ran and response.stop_reason != "refusal"

print(
    json.dumps(
        {
            "stop_reason": response.stop_reason,
            "model": response.model,
            "served_by_fallback": served_by_fallback,
        }
    )
)

Anthropicは、モデルの能力に応じて、各モデルごと、および各ポリシーカテゴリごとに個別にセーフガードを設定しています。カテゴリによっては、フラグが立てられたリクエストは能力の低いモデルにフォールバックされるか、拒否されます。"default"モードは、これらのモデルごと・カテゴリごとの推奨をエンコードしているため、拒否されたリクエストはそのカテゴリに対してAnthropicが推奨するモデルで再試行されます。いずれの場合もフォールバックは可視化されます。レスポンスには処理したモデルが示され、fallbackコンテンツブロックが引き継ぎを示します。

ルーティングはサーバーサイドで適用され、Models APIでモデルごとに公開されることはありません。拒否されたリクエストをどのモデルが処理したかを確認するには、このページのサンプルのように、レスポンスのトップレベルのmodelフィールドを確認し、usage.iterations内のfallback_messageエントリを探してください。

フォールバックをトリガーするのは安全性分類器による拒否のみです。リクエストされたモデルでのレート制限、過負荷、またはサーバーエラーは、そのまま返されます。

独自のフォールバックモデルの指定

デフォルトルーティングの代わりに、fallbacksを最大3つのモデルのリストに設定できます。リクエストされたモデルが拒否すると、APIはチェーン内の次のモデルで同じリクエストを実行します。アプリケーションで検証済みのモデルを固定するなど、拒否されたリクエストをどのモデルが処理するかを正確に制御したい場合に、この形式を使用してください。

指定したフォールバックモデルはサイズ超過画像チェックの対象になります。画像ブロックに"oversized_image": "error"を設定したリクエストは、リクエストされたモデルと指定されたすべてのフォールバックに対して事前にチェックされ、いずれかがその画像をリサイズすることになる場合は拒否されます。また、拒否時に報告されるリスケール目標はそれらすべてに適合するものになります。

ハイライトされた行が、デフォルトルーティングのリクエストとの唯一の違いです。

client = Anthropic()

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

fallbacksリストにはいくつかのルールが適用されます：

• エントリは順番に試行されます。各エントリは、他のエントリおよびリクエストされたモデルと異なっている必要があります。
• 各エントリは、リクエストされたモデルの許可されたターゲットのいずれかである必要があります。ベータヘッダーを設定すると、そのリストはModels APIのモデルエントリにallowed_fallback_modelsとして公開されます。
• 各エントリはmodelを指定し、その試行に限ってmax_tokens、thinking、output_config、speedをオーバーライドできます。
• リクエストは、指定されたすべてのモデルへの直接リクエストとして有効である必要があります。フォールバックモデルがリクエストで使用されている機能をサポートしていない場合、APIはリクエストを事前に拒否します。
• デフォルトモードと同様に、フォールバックをトリガーするのは安全性分類器による拒否のみです。リクエストされたモデルでのレート制限、過負荷、またはサーバーエラーは、そのまま返されます。
• フォールバックモデルがレート制限されているか過負荷の場合、フォールバック試行は行われず、代わりに直前の拒否が返されます。その場合、拒否のstop_details.recommended_modelが直接再試行すべきモデルを示します。予想される拒否量に合わせてフォールバックモデルのレート制限を設定してください。そうしないと、負荷がかかった際にフォールバックが拒否に劣化します。

レスポンスの形式はどちらのモードでも同じです。ターンを処理したモデルはトップレベルのmodelフィールドに表示され、fallbackコンテンツブロックが引き継ぎを示し、usage.iterationsが各試行を記録します。

レスポンスに含まれる内容

レスポンスは他のメッセージと同様ですが、2つの追加要素があります：

• トップレベルのmodelフィールドは、返されたメッセージを生成したモデルを報告します。それがリクエストされたモデルであってもフォールバックであっても同様です。
• fallbackコンテンツブロックは、content内で1つのモデルの出力が次のモデルに引き継がれる各ポイントを示します：{"type": "fallback", "from": {"model": ...}, "to": {"model": ...}}。
  • 拒否したホップがリクエストされたモデルである場合、from.modelは送信したモデル文字列をそのまま返します。
  • to.modelは常に、続行するモデルの解決済みIDです。

出力が一切ない段階での拒否の場合、fallbackブロックが最初のコンテンツブロックになります。例えば、デフォルトルーティングが拒否のカテゴリに対してClaude 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,
    "cache_read_input_tokens": 0,
    "cache_creation_input_tokens": 0,
    "iterations": [
      {
        "type": "message",
        "model": "claude-fable-5",
        "input_tokens": 535,
        "output_tokens": 0,
        "cache_read_input_tokens": 0,
        "cache_creation_input_tokens": 0
      },
      {
        "type": "fallback_message",
        "model": "claude-opus-4-8",
        "input_tokens": 412,
        "output_tokens": 264,
        "cache_read_input_tokens": 0,
        "cache_creation_input_tokens": 0
      }
    ]
  }
}

usage.iterations配列はすべての試行を記録します。拒否したモデルは通常のmessageエントリとして表示され、ターンを処理したモデルはfallback_messageエントリとして表示されます。チェーン内のすべてのモデルが拒否した場合、レスポンスは最後のモデルの拒否となり、それ以前の各ホップにはmessageエントリ、最後のホップにはfallback_messageエントリが付きます。

スティッキールーティングにより、後続のターンが直接フォールバックモデルに送信されることがあります。そのようなターンにはfallbackコンテンツブロックが含まれません。そのターンではどのモデルも拒否していないためです。usage.iterations内のfallback_messageエントリ、リクエストされたモデルのmessageエントリがないこと、およびレスポンスのmodelフィールドによって識別してください。

会話の継続

次のターンでは、受け取ったアシスタントコンテンツをそのまま送り返してください。出力途中のフォールバックの後、contentには拒否したモデルが引き継ぎ前に生成したブロックタイプが含まれることがあります。以下の表は、ターンをエコーする際にどれを保持し、どれを削除するかを示しています。

ストリーミング

ストリーミングリクエストでは、再試行は同じストリーム上で行われ、すでに受信したものが無効になることはありません。何が表示されるかは、拒否がいつ発生するかによって異なります。

出力が一切ない段階で拒否が発生した場合：

• 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に表示されます。

課金とレート制限

出力を一切生成する前に拒否した試行は課金されません。そのトークンはusage.iterationsエントリに報告されますが、課金されません。出力を生成したすべての試行（レスポンスの途中で拒否したものを含む）は、それを実行したモデルの料金で個別に課金されます。usage.iterations配列は、課金対象の試行ごとの記録です。トップレベルのusageカウントは、返されたメッセージを生成した試行のみを表します。異なるモデルのトークンが1つのフィールドに合算されることはありません。

拒否したものを含め、実行されたすべての試行は、それぞれのモデルのレート制限にカウントされます。

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

会話がフォールバックした後、APIはどのモデルがそれを処理したかを記録します。その会話に対するfallbacksを含む後続のリクエストは、リクエストされたモデルを実行せずに、直接そのフォールバックモデルに送られます。これにより、毎ターン予測どおりに再び拒否されるであろう試行に対して支払うことを避けられます。

ルーティング決定のいくつかの特性：

• 約1時間保持され、組織にスコープされます。
• 会話プレフィックスのコンテンツハッシュと、それを処理したモデルとして保存されます。メッセージコンテンツ自体は保存されません。
• ベストエフォートであるため、コードはリクエストされたモデルがいつでも再び試行される可能性に対応する必要があります。

スティッキールーティングはストリーミングリクエストと非ストリーミングリクエストの両方に適用されます。ストリーミングリクエストでは、ルーティング決定はストリームが開く前に行われるため、message_startイベントのmodelフィールドにはすでにフォールバックモデルのIDが含まれています。

SDKミドルウェアによるクライアントサイドフォールバック

すべてのAnthropic SDKには、拒否フォールバックミドルウェアが含まれています。フォールバックモデルのリストを使用してクライアントで一度設定します。その後、client.beta.messagesを介した呼び出しは、どのプラットフォームでも拒否されたリクエストを自動的に再試行します。ミドルウェアは処理するすべてのリクエストにfallback-credit-2026-07-01ベータヘッダーも送信するため、リクエストごとの設定なしで再試行の料金が再計算されます。

セットアップ

ミドルウェアをクライアントコンストラクタに渡し、会話のリクエスト間で1つのBetaFallbackStateインスタンスを共有します。

from anthropic import Anthropic, BetaFallbackState, BetaRefusalFallbackMiddleware

# 拒否が発生した場合、ミドルウェアは指定されたフォールバックモデルで再試行し、
# 処理するすべてのリクエストにfallback-creditベータヘッダーを自動的に送信します。
client = Anthropic(
    middleware=[BetaRefusalFallbackMiddleware([{"model": "claude-opus-4-8"}])],
)

state = BetaFallbackState()  # pins follow-ups to the model that accepted

# ストリーミング: 拒否が発生した場合、ミドルウェアはフォールバックモデルで再試行し、
# そのイベントを開いているストリームに継ぎ足します。
with (
    state,
    client.beta.messages.stream(
        max_tokens=1024,
        model="claude-fable-5",
        messages=[{"role": "user", "content": "Hello, Claude"}],
    ) as stream,
):
    for text in stream.text_stream:
        print(text, end="", flush=True)
    final_message = stream.get_final_message()
print(f"\nserved by: {final_message.model}")

# 非ストリーミング: 状態を再利用することで会話が固定されたまま維持されます。
with state:
    message = client.beta.messages.create(
        max_tokens=1024,
        model="claude-fable-5",
        messages=[{"role": "user", "content": "Hello, Claude"}],
    )
print(f"served by: {message.model}")

動作

• 再試行はフォールバックリストを順番にたどります。フォールバックモデル自体が拒否した場合、リクエストは次のエントリに渡されます。
• リスト内のすべてのモデルが拒否した場合、ミドルウェアはエラーを発生させるのではなく、最終的な拒否（最後のモデルの拒否レスポンス）を返します。
• Claude Fable 5.1またはClaude Fable 5の思考ブロックは変更されずにそのまま渡されます。各再試行は元のリクエストボディを再送信し、ミドルウェアが後続のリクエストで会話履歴から削除する唯一のブロックは、自身が追加したfallback境界ブロックです。フォールバックモデルはClaude Fable 5.1のブロックを読み取ることができません。これらはそのモデルまたはより新しいモデルに対してのみ保持されるため、APIがそれらを削除します。
• ミドルウェアを介して処理されたレスポンスには、サーバーサイドフォールバックのレスポンスと同様に、各モデル境界にfallbackコンテンツブロックが含まれます。ミドルウェアは後続のリクエストでこれらのブロックを自動的に管理します。
• 受け入れたモデルはBetaFallbackStateに記録されるため、状態を共有するフォローアップリクエストは、拒否したモデルに再度問い合わせるのではなく、そのモデルに固定されたままになります。

再試行を自分で記述する

生のHTTPまたはカスタム再試行ロジックを使用する場合は、ミドルウェアがラップしているパターンを実装します：

1. 1

   拒否を検出する

   レスポンスにstop_reason: "refusal"があるか確認します。

2. 2

   フォールバックモデルで再送信する

   modelをClaude Opus 4.8などのフォールバックモデルに設定して、同じリクエストを送信します。Claude Fable 5.1またはClaude Fable 5が拒否したリクエストは、通常、別のモデルで処理できます。会話履歴の扱い方は、フォールバッククレジットを引き換えるかどうかによって異なります：

   • クレジットを引き換えない場合： 以前のthinkingおよびredacted_thinkingブロックをそのまま残すことも、入力トークンを節約するために削除することもできます。いずれにしてもフォールバックモデルはそれらを使用できません。Claude Fable 5のブロックは無視され、Claude Fable 5.1のブロックはそのモデルまたはより新しいモデルに対してのみ保持されるため、APIがそれらを削除します。
   • クレジットを引き換える場合： 引き換えには完全一致が必要なため、ボディを変更せずに送信してください。引き換え時にはサーバーが以前のモデルの思考ブロックを処理するため、削除しないでください（拒否されたリクエストと一致する必要があるフィールドを参照）。
3. 3

   フォールバックモデルを使い続ける

   マルチターンの会話では、元に戻すのではなく、後続のターンでもフォールバックモデルを使い続けてください。

手動再試行では、フォールバックモデルのプロンプトキャッシュが最初から書き込まれるため、既存のキャッシュを読み取るよりもコストがかかります。フォールバッククレジットはそのコストを払い戻します。自分で構築するすべての再試行で引き換えてください。

Message Batchesにおける拒否

Message Batch内で拒否されたリクエストは、stop_reason: "refusal"を持つresult.type: "succeeded"として返されます。バッチ結果は同期レスポンスと同じstop_detailsオブジェクトを持つため、stop_reasonまたはstop_details.typeのいずれかで拒否を検出できます。1つの違いとして、バッチの拒否はフォールバッククレジットを発行しないため、バッチ結果のstop_detailsにfallback_credit_tokenが含まれることはありません。

サーバーサイドフォールバックはバッチでは利用できません（fallbacksを含むバッチリクエストは項目ごとのエラー結果を生成します）。拒否されたバッチ項目を再試行するには：

1. 結果から拒否された項目を収集します。
2. マルチターン履歴からClaude Fable 5.1またはClaude Fable 5の思考ブロックを削除します。
3. 新しいバッチまたは直接リクエストとして、フォールバックモデルで再送信します。

よくある落とし穴

• 別のモデルで再試行してください。 拒否されたリクエストを同じモデルに再送信すると、通常は再び拒否されます。再試行はフォールバックモデルに向けてください。
• 再試行の予算はターンごとやセッションごとではなく、リクエストごとに設定してください。 1つのターンで複数の拒否が発生することがあります。例えば、エージェントとそのサブエージェントなどです。
• すべてのリクエストパスでフォールバックを設定してください。 再試行ハンドラー、エラー回復ブランチ、バックグラウンドワーカーのすべてに必要です。フォールバックなしでリクエストを再発行するハンドラーは、まさに最も必要とされる可能性の高いリクエストで保護を失います。
• サブエージェント呼び出しには独自のフォールバックを設定してください。 fallbacksパラメータは、ツール実行内部から行われるモデル呼び出しには伝播しません。
• フォールバックは周囲の状態ではなく、リクエストのプロパティにしてください。 共有フラグ、キャッシュされた設定値、またはグローバルトグルは同期がずれ、気づかないうちにリクエストが保護されないままになる可能性があります。フォールバックが有効であることを確認できない場合は、有効であると仮定するのではなく、設定してください。
• 拒否を独自のシグナルとして計測してください。 拒否はHTTP 200であるため、エラー率や5xxレスポンスに基づく監視では検出されません。拒否ごとに1つのイベント、フォールバックで処理されたレスポンスごとに1つのイベント（usage.iterations内のfallback_messageエントリが後者を示します）を発行し、2つのカウントの差に対してアラートを設定してください。
• contentやstop_detailsの内部フィールドではなく、stop_reasonまたはstop_details.typeで分岐してください。 stop_detailsオブジェクトは拒否時に常に存在しますが、そのcategoryおよびexplanationフィールドはnullになることがあります。stop_reasonが"refusal"に等しいかどうかを直接確認してください。

次のステップ