拒否とフォールバック

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

Claude Fable 5上で構築していて、拒否されたリクエストを自動的に別のモデルにフォールスルーさせたい場合に、このページをお読みください。また、レスポンスで"refusal"を確認したばかりで、次に何をすべきか知りたい場合にも適用されます。

stop_reasonの値の完全なリストは、停止理由とフォールバックに記載されています。拒否されたリクエストの課金方法、および再試行時にプロンプトキャッシングの二重課金を回避する方法の詳細は、フォールバッククレジットに記載されています。これらすべてをラップするSDKヘルパーについては、SDKミドルウェアを参照してください。エンドツーエンドの実例については、フォールバックと課金のクックブックを参照してください。

最もシンプルな設定：リクエストでフォールバックモデルを指定すると、APIが再試行を処理します。

await client.beta.messages.create({
  model: "claude-fable-5",
  max_tokens: 1024,
  messages,
  betas: ["server-side-fallback-2026-06-01"],
  fallbacks: [{ model: "claude-opus-4-8" }]
});

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

拒否レスポンスの内容

拒否は、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呼び出し内で再試行します。最大3つのフォールバックモデルを指定すると、Claude Fable 5が拒否した場合、APIは同じリクエストでチェーン内の次のモデルを実行します。回答したモデルを示す1つのレスポンスが返されるため、ユーザーは1回のラウンドトリップで回答を得られます。

リクエストの作成

fallbacksパラメータでフォールバックモデルを指定し、server-side-fallback-2026-06-01ベータヘッダーを送信します。

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-06-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,
        }
    )
)

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

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

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

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

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

出力前の拒否では、fallbackブロックが最初のコンテンツブロックになります。

{
  "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ミドルウェアを使用したクライアントサイドフォールバック

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

設定方法

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

# 拒否が発生すると、ミドルウェアは指定されたフォールバックモデルで再試行し、
# 処理するすべてのリクエストにフォールバッククレジットのベータヘッダーを自動的に送信します。
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 event in stream:
        if event.type == "text":
            print(event.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の思考ブロックは自動的に処理されます。ミドルウェアは再試行からそれらを削除し、後続のリクエストで会話履歴内のそれらを管理します。
• ミドルウェアを通じて処理されたレスポンスには、サーバーサイドフォールバックレスポンスと同様に、各モデル境界にfallbackコンテンツブロックが含まれます。ミドルウェアは、後続のリクエストでそれらのブロックを管理します。
• 受け入れたモデルはBetaFallbackStateに記録されるため、状態を共有する後続のリクエストは、拒否したモデルに再度問い合わせるのではなく、そのモデルに固定されたままになります。

Message Batchesでの拒否

Message Batch内の拒否されたリクエストは、stop_reason: "refusal"を含むresult.type: "succeeded"として返されます。バッチ結果ではstop_detailsフィールドがnullになる場合があるため、stop_reasonを直接確認して拒否を検出してください。

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

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

よくある落とし穴

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

次のステップ