プロンプトキャッシュはモデルごとに管理されます。Claude Fable 5 がリクエストを拒否し、別のモデルで再試行する場合、Claude Fable 5 用にすでにキャッシュされていた会話プレフィックスを新しいモデルのキャッシュにゼロから書き込む必要があり、キャッシュ書き込みはキャッシュ読み取りよりもコストが高くなります。「fallback credit」(フォールバッククレジット)はこの追加コストを解消します。拒否レスポンスにはクレジットトークンが含まれており、再試行時にそのトークンをエコーバックすることで、再試行は最初から新しいモデルで会話が行われていたかのように課金されます。
このページが必要になるのは、再試行を自分で構築する場合のみです。つまり、Ruby または PHP SDK、生の HTTP、またはカスタム再試行ロジックを使用する場合です。サーバーサイドフォールバックと SDK ミドルウェアは、フォールバッククレジットを自動的に適用します。いずれかを使用している場合は、このページをスキップしてください。
拒否とフォールバックでは、拒否の検出とフォールバックアプローチの選択について説明しています。キャッシュ読み取りとキャッシュ書き込みという用語に馴染みがない場合は、プロンプトキャッシングで説明しています。
ベータヘッダーでオプトインする
拒否される可能性のあるリクエストを anthropic-beta: fallback-credit-2026-06-01 ヘッダー付きで送信します。server-side-fallback-2026-06-01 ヘッダーでも同じフィールドが付与されます。
拒否レスポンスから 2 つのフィールドを読み取る
拒否時、stop_details には、クレジットを表す不透明な文字列である fallback_credit_token と、どの再試行ボディ形式を使用すべきかを示すブール値である fallback_has_prefill_claim が含まれます。その拒否に対してクレジットが利用できない場合、両方とも null になります。
再試行を構築する
拒否されたリクエストボディから開始します。model をフォールバックモデルに設定し、トークンをトップレベルの fallback_credit_token パラメータとして追加します。下の表からボディ形式を選択してください。
同じヘッダーで再試行を送信する
同じ fallback-credit-2026-06-01 ベータヘッダーを付けて再試行を送信します。再試行でトークンを引き換えるには、このヘッダーが必要です。
fallback_has_prefill_claim フィールドは、再試行が最初からやり直すのではなく、拒否されたモデルの部分的な出力を継続できるかどうかを示します。
fallback_has_prefill_claim | 再試行ボディ |
|---|---|
true | 拒否されたリクエストボディをそのまま使用し、さらに content が拒否されたレスポンスの content をエコーする assistant メッセージを 1 つ末尾に追加します。再試行モデルは、拒否されたモデルが停止した位置からレスポンスを継続し、完了済みのサーバーツール呼び出しは再実行されません。 |
false | 拒否されたリクエストボディをそのまま使用します。 |
以下の例では、拒否される可能性のあるリクエストを送信し、Claude Opus 4.8 に対する再試行でクレジットトークンを引き換え、再試行が拒否された場合で説明されている拒否ラダーに沿って段階的にデグレードします。
フォールバッククレジットは、Claude API、Claude Platform on AWS、Amazon Bedrock、Vertex AI、Microsoft Foundry でベータ版として提供されています。Message Batches の結果で返されるクレジットトークンは引き換えできません。引き換えは直接の Messages API リクエストにのみ適用されます。
再試行モデルは、拒否されたモデルの許可されたフォールバックターゲットのいずれかである必要があります。リリース時点で、Claude Fable 5 の許可されたターゲットは Claude Opus 4.8(claude-opus-4-8)です。
払い戻しは再試行の usage で確認できます。トークンなしで同じリクエストを送信した場合と比較して、cache_creation_input_tokens が低くなり、cache_read_input_tokens が同じ量だけ高くなります。差分がゼロの場合、トークンは受理されたものの、再価格設定するものがなかったことを意味します。たとえば、再試行モデルのキャッシュがすでにウォーム状態だった場合などです。
ほとんどの再試行は最初の試行で引き換えられます。引き換えられない場合、API は次に何を試すべきかを示す 400 エラーを返します。
継続が拒否された場合:変更なしのボディを再送信する
assistant メッセージを追加した再試行が 400 エラーで拒否された場合、拒否されたリクエストボディを変更せずに、トークンを付けたまま再送信します。
トークンが拒否された場合:トークンを削除する
変更なしのボディも、メッセージに fallback_credit_token が含まれる 400 エラーで拒否された場合、トークンなしで再試行します。クレジットは失われますが、再試行自体は通ります。
拒否されたリクエストがサーバーツールを実行していた場合、トークンなしの再試行はそれらのツールを再実行し、再課金します。その場合は、トークンなしの再試行にフォールスルーするのではなく、400 エラーを呼び出し元に表示してください。
以下のセクションでは、エッジケースと完全な引き換えルールについて説明します。ほとんどの統合ではこれらは必要ありません。
Was this page helpful?
client = Anthropic()
request = {
"max_tokens": 1024,
"messages": [{"role": "user", "content": "Hello, Claude"}],
}
def send(model, body):
return client.beta.messages.create(
model=model, betas=["fallback-credit-2026-06-01"], **body
)
response = send("claude-fable-5", request)
if (
response.stop_reason == "refusal"
and (details := response.stop_details)
and (token := details.fallback_credit_token)
):
exact_body = request | {"fallback_credit_token": token}
# claimがFalseでない限り、継続形式を優先します
if details.fallback_has_prefill_claim is not False:
# 拒否応答の内容をエコーし、最後のテキストブロックから末尾の空白を
# 除去します(プリフィル検証器が拒否するため。サーバー側の照合はこの編集を許容)。
# ツール使用リクエストでは、対になっていないtool_useブロックも省略し、
# 省略後に再度空白を除去します。
echoed = [block.model_dump() for block in response.content]
match echoed:
case [*_, {"type": "text"} as final_block]:
final_block["text"] = final_block["text"].rstrip()
attempt = exact_body | {
"messages": [
*request["messages"],
{"role": "assistant", "content": echoed},
]
}
else:
attempt = exact_body
try:
response = send("claude-opus-4-8", attempt)
except BadRequestError as error:
if "redemption temporarily unavailable" in str(error):
raise # Transient: retry with the token within its five-minute window
try:
# トークンを保持したまま、変更前の本文にフォールバックします
response = send("claude-opus-4-8", exact_body)
except BadRequestError as error:
if "redemption temporarily unavailable" in str(error):
raise # Transient: retry with the token within its five-minute window
# トークン自体が拒否された場合:トークンを放棄し、なしで再試行します。
response = send("claude-opus-4-8", request)
print(json.dumps({"stop_reason": response.stop_reason, "model": response.model}))すべての stop_reason 値とその処理方法。