拒否とフォールバック

Claude Fable 5とClaude Opus 5には、リクエストを拒否する可能性のある安全性分類器が含まれています。拒否が発生した場合、エラーではなく、stop_reason: "refusal"を含む通常のレスポンスを受け取ります。通常は、同じリクエストを別のClaudeモデルに送信することで回答を得ることができます。このページでは、拒否を認識する方法と、その再試行を設定する方法を説明します。

Claude Fable 5またはClaude Opus 5上で構築していて、拒否されたリクエストを自動的に別のモデルにフォールスルーさせたい場合に、このページをお読みください。また、レスポンスで"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: 人間が読める説明です。テキストは安定していないため、解析するのではなく表示してください。
• 拒否が名前付きカテゴリにマッピングされない場合、両方のフィールドはnullになります。このnullはプレースホルダーではなく、通常の恒久的な値です。
• stop_details自体は、refusal以外のすべての停止理由ではnullです。

拒否は、出力が生成される前、または部分的な出力の後のストリーム途中で発生する可能性があります。いずれの場合も、部分的な出力は不完全なものとして扱い、破棄してください。



フォールバックアプローチの選択

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

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



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

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



リクエストの作成

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

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はチェーン内の次のモデルで同じリクエストを実行します。アプリケーションで検証済みのモデルを固定するなど、拒否されたリクエストを処理するモデルを正確に制御したい場合に、この形式を使用してください。

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リストにはいくつかのルールが適用されます:

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

明示的リスト形式はserver-side-fallback-2026-06-01ベータヘッダーでも動作しますが、"default"モードは動作しません。

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



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

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

• トップレベルのmodelフィールドは、返されたメッセージを生成したモデルを報告します。これはリクエストされたモデルまたはフォールバックのいずれかです。
• fallbackコンテンツブロックは、content内であるモデルの出力が次のモデルに引き継がれる各ポイントをマークします: {"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エントリが含まれます。



会話の継続

次のターンでは、受け取ったとおりにアシスタントのコンテンツを送り返してください。出力途中のフォールバック後、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に表示されます。



SDKミドルウェアを使用したクライアントサイドフォールバック

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



セットアップ

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

from anthropic import Anthropic, BetaFallbackState, BetaRefusalFallbackMiddleware

# 拒否が発生した場合、ミドルウェアは指定されたフォールバックモデルで再試行し、
# 処理するすべてのリクエストにフォールバッククレジットのベータヘッダーを自動的に送信します。
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のthinkingブロックは変更されずに通過します。各再試行は元のリクエストボディを再送信し、ミドルウェアが以降のリクエストで会話履歴から削除するブロックは、自身が追加したfallback境界ブロックのみです。
• ミドルウェアを介して処理されたレスポンスには、サーバーサイドフォールバックのレスポンスと同様に、各モデル境界にfallbackコンテンツブロックが含まれます。ミドルウェアは以降のリクエストでこれらのブロックを管理します。
• 受け入れたモデルはBetaFallbackStateに記録されるため、状態を共有するフォローアップリクエストは、拒否したモデルに再度問い合わせるのではなく、そのモデルに固定されたままになります。



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のthinkingブロックを削除します。
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"と等しいかを直接確認してください。



次のステップ