プロンプトキャッシュはモデルごとに分かれています。Claude Fable 5がリクエストを拒否し、別のモデルで再試行する場合、Claude Fable 5用にすでにキャッシュされていた会話のプレフィックスを、新しいモデルのキャッシュに最初から書き込む必要があります。キャッシュ書き込みはキャッシュ読み取りよりもコストが高くなります。「fallback credit」(フォールバッククレジット)はこの余分なコストを取り除きます。拒否レスポンスにはクレジットトークンが含まれており、再試行時にそのトークンをエコーバックすると、その再試行は最初から新しいモデルで会話していたかのように課金されます。
このページが必要になるのは、再試行を自分で構築する場合のみです。つまり、生のHTTPを使う場合や、カスタムの再試行ロジックを使う場合です。サーバーサイドフォールバックとSDKミドルウェアは、フォールバッククレジットを自動的に適用します。いずれかを使用している場合は、このページをスキップしてください。
拒否とフォールバックでは、拒否の検出とフォールバック手法の選択について説明しています。キャッシュ読み取りやキャッシュ書き込みという用語に馴染みがない場合は、プロンプトキャッシングで説明しています。
ベータヘッダーでオプトインする
拒否される可能性のあるリクエストを、anthropic-beta: fallback-credit-2026-07-01ヘッダーを付けて送信します。server-side-fallback-2026-07-01ヘッダーも同じフィールドを付与します。また、以前のfallback-credit-2026-06-01ヘッダーも引き続き受け付けられ、同じフィールドを付与します。
拒否レスポンスから2つのフィールドを読み取る
拒否時には、stop_detailsに2つのフィールドが含まれます。
fallback_credit_token: クレジットを表す不透明な文字列。fallback_has_prefill_claim: どの再試行ボディの形式を使うべきかを示すブール値。その拒否に対してクレジットが利用できない場合、どちらもnullになります。
再試行を構築する
拒否されたリクエストボディから始めます。modelをフォールバックモデルに設定し、トークンをトップレベルのfallback_credit_tokenパラメータとして追加します。ボディの形式は以下の表から選択します。
同じヘッダーを付けて再試行を送信する
同じfallback-credit-2026-07-01ベータヘッダーを付けて再試行を送信します。トークンを引き換えるには、再試行にこのヘッダーが必要です。
fallback_has_prefill_claimフィールドは、再試行が最初からやり直すのではなく、拒否したモデルの部分的な出力を継続できるかどうかを示します。
fallback_has_prefill_claim | 再試行ボディ |
|---|---|
true | 拒否されたリクエストボディをそのまま使い、拒否されたレスポンスのcontentをエコーしたcontentを持つassistantメッセージを1つ末尾に追加します。再試行モデルは、拒否したモデルが停止した箇所からレスポンスを継続し、完了済みのサーバーツール呼び出しは再実行されません。 |
false | 拒否されたリクエストボディをそのまま使います。 |
次の例では、拒否される可能性のあるリクエストを行い、Claude Opus 4.8に対する再試行でクレジットトークンを引き換えます。再試行の試みが却下された場合、この例は却下ラダーを通じて段階的に単純化します。これは再試行が却下された場合で説明する、段階的に単純な再試行形式のシーケンスです。
client = Anthropic()
request = {
"max_tokens": 1024,
"messages": [{"role": "user", "content": "Hello, Claude"}],
}
def send(model: str, body: dict[str, object]) -> BetaMessage:
return client.beta.messages.create(
model=model, betas=["fallback-credit-2026-07-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}
# クレームがFalseでない限り、継続形式を優先します
if details.fallback_has_prefill_claim is not False:
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 error.message:
raise # Transient: retry with the token within its five-minute window
try:
# トークンを保持したまま、変更されていない本文にフォールバックします
response = send("claude-opus-4-8", exact_body)
except BadRequestError as retry_error:
if "redemption temporarily unavailable" in retry_error.message:
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、Amazon Bedrock、AWS上のClaude Platform、Google Cloud、Microsoft Foundryでベータ版として提供されています。Message Batchesでの拒否はクレジットトークンを発行せず、引き換えは直接のMessages APIリクエストにのみ適用されます。バッチリクエストで渡されたトークンは受け付けられますが、無視されます。
再試行モデルは、拒否したモデルの許可されたフォールバックターゲットのいずれかである必要があります。Claude Fable 5の許可されたターゲットは、Claude Opus 4.8(claude-opus-4-8)とClaude Opus 5(claude-opus-5)です。
払い戻しは再試行のusageで確認できます。トークンなしで同じリクエストを送った場合に報告される値と比較して、cache_creation_input_tokensが低くなり、cache_read_input_tokensが同じ量だけ高くなります。差分がゼロの場合は、トークンは受理されたものの、再計算するものがなかったことを意味します。たとえば、再試行モデルのキャッシュがすでにウォームだった場合などです。
ほとんどの再試行は最初の試みで引き換えられます。そうでない場合、APIは次に何を試すべきかを示す400エラーを返します。
継続が却下された場合: 変更なしのボディを再送する
assistantメッセージを追加した再試行が400エラーで却下された場合は、拒否されたリクエストボディを変更せずに、トークンを付けたまま再送します。
トークンが却下された場合: トークンを外す
変更なしのボディも、メッセージにfallback_credit_tokenが含まれる400エラーで却下された場合は、トークンなしで再試行します。クレジットは失われますが、再試行自体は通ります。
拒否されたリクエストがサーバーツールを実行していた場合、トークンなしの再試行はそれらのツールを再実行し、再課金します。その場合は、トークンなしの再試行にフォールスルーするのではなく、400エラーを呼び出し元に提示してください。
以下のセクションでは、エッジケースと完全な引き換えルールについて説明します。ほとんどの統合では必要ありません。
拒否を検出し、サーバーサイドフォールバック、SDKミドルウェア、手動再試行のいずれかを選択します。
キャッシュ読み取りとキャッシュ書き込みの課金方法。
すべてのstop_reasonの値とその処理方法。
フォールバッククレジットを自動的に適用するSDKヘルパー。
Was this page helpful?