プロンプトキャッシュはモデルごとに管理されます。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には2つのフィールドが含まれます。
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をエコーするアシスタントメッセージを1つ末尾に追加します。再試行モデルは、拒否されたモデルが停止した箇所からレスポンスを継続し、完了済みのサーバーツール呼び出しは再実行されません。 |
false | 拒否されたリクエストボディをそのまま使用します。 |
次の例では、拒否される可能性のあるリクエストを行い、Claude Opus 4.8に対する再試行でクレジットトークンを引き換えます。再試行の試みが拒否された場合、この例は拒否ラダーを通じて段階的に降格します。これは、再試行が拒否された場合で説明されている、段階的により単純な再試行形式のシーケンスです。
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}))フォールバッククレジットは、Claude API、Claude Platform on AWS、Amazon Bedrock、Google Cloud、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エラーを返します。
継続が拒否された場合:変更なしのボディを再送信する
アシスタントメッセージを追加した再試行が400エラーで拒否された場合、拒否されたリクエストボディを変更せずに、トークンを付けたまま再送信します。
トークンが拒否された場合:トークンを削除する
変更なしのボディも、メッセージにfallback_credit_tokenが含まれる400エラーで拒否された場合、トークンなしで再試行します。クレジットは失われますが、再試行自体は通ります。
拒否されたリクエストがサーバーツールを実行していた場合、トークンなしの再試行はそれらのツールを再実行し、再課金します。その場合は、トークンなしの再試行にフォールスルーするのではなく、400エラーを呼び出し元に表示してください。
以下のセクションでは、エッジケースと完全な引き換えルールについて説明します。ほとんどの統合では、これらは必要ありません。
拒否を検出し、サーバーサイドフォールバック、SDKミドルウェア、手動再試行のいずれかを選択します。
キャッシュ読み取りとキャッシュ書き込みがどのように課金されるかを説明します。
すべてのstop_reason値とその処理方法を説明します。
フォールバッククレジットを自動的に適用するSDKヘルパーです。
Was this page helpful?