Claude Platform Docs
MessagesClaudeで構築する

フォールバッククレジット

拒否されたリクエストを別のモデルで再試行する際に、プロンプトキャッシュのコストを二重に支払うことを回避します。

プロンプトキャッシュはモデルごとに保持されます。あるモデルがリクエストを拒否し、別のモデルで再試行する場合、最初のモデル向けにすでにキャッシュされていた会話のプレフィックスは、新しいモデルのキャッシュにゼロから書き込む必要があります。キャッシュ書き込みはキャッシュ読み取りよりもコストがかかります。「fallback credit」（フォールバッククレジット）はその追加コストを取り除きます。拒否レスポンスにはクレジットトークンが含まれており、再試行時にそのトークンをそのまま送り返すと、再試行は会話が最初から新しいモデル上で行われていたかのように課金されます。

このページが必要になるのは、生のHTTPやカスタムの再試行ロジックを使って、再試行を自分で構築する場合のみです。サーバーサイドフォールバックとSDKミドルウェアはフォールバッククレジットを自動的に適用します。いずれかを使用している場合は、このページを読み飛ばしてください。

拒否とフォールバックでは、拒否の検出とフォールバック手法の選択について説明しています。キャッシュ読み取りやキャッシュ書き込みという用語に馴染みがない場合は、プロンプトキャッシングで説明しています。

基本的な流れ

  1. ベータヘッダーでオプトインする

    拒否される可能性のあるリクエストを、anthropic-beta: fallback-credit-2026-07-01 ヘッダーを付けて送信します。server-side-fallback-2026-07-01 ヘッダーでも同じフィールドが付与されます。また、以前の fallback-credit-2026-06-01 ヘッダーも引き続き受け付けられ、同じフィールドが付与されます。

  2. 拒否レスポンスから2つのフィールドを読み取る

    拒否時には、stop_details に2つのフィールドが含まれます。

    • fallback_credit_token: クレジットを表す不透明な文字列です。
    • fallback_has_prefill_claim: どちらの再試行ボディ形式を使用すべきかを示すブール値です。

    その拒否に対してクレジットが利用できない場合、両方とも null になります。

  3. 再試行を構築する

    拒否されたリクエストボディから始めます。model をフォールバックモデルに設定し、トークンをトップレベルの fallback_credit_token パラメータとして追加します。以下の表からボディ形式を選択してください。

  4. 同じヘッダーを付けて再試行を送信する

    同じ fallback-credit-2026-07-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: 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}
    # claimが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、Claude Platform on AWS、Google Cloud、および Microsoft Foundry でベータ版として提供されています。Message Batches での拒否ではクレジットトークンは発行されず、引き換えは直接の Messages API リクエストにのみ適用されます。バッチリクエストで渡されたトークンは受け付けられますが無視されます。

再試行モデルは、拒否したモデルに許可されたフォールバック先のいずれかである必要があります。Claude Fable 5.1 および 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 エラーを返します。

  1. 継続が拒否された場合: 変更なしのボディを再送信する

    アシスタントメッセージを追加した再試行が 400 エラーで拒否された場合は、拒否されたリクエストボディを変更せずに、トークンを付けたまま再送信します。

  2. トークンが拒否された場合: トークンを外す

    変更なしのボディも、メッセージに fallback_credit_token の名前が含まれる 400 エラーで拒否された場合は、トークンなしで再試行します。クレジットは失われますが、再試行自体は通ります。

リファレンス

以下のセクションでは、エッジケースと完全な引き換えルールについて説明します。ほとんどの統合では必要ありません。

次のステップ

拒否とフォールバック

拒否を検出し、サーバーサイドフォールバック、SDKミドルウェア、手動再試行のいずれかを選択します。

プロンプトキャッシング

キャッシュ読み取りとキャッシュ書き込みの課金方法。

停止理由とフォールバック

すべての stop_reason の値とその処理方法。

SDKミドルウェア

フォールバッククレジットを自動的に適用する SDK ヘルパー。

Was this page helpful?