Claude Platform Docs
Messages使用 Claude 構建

備援抵免

當您在另一個模型上重試被拒絕的請求時，避免重複支付提示快取的費用。

提示快取是依模型區分的。當某個模型拒絕一個請求，而您在另一個模型上重試時，已為第一個模型快取的對話前綴必須從頭寫入新模型的快取。快取寫入的費用高於快取讀取。「Fallback credit」（備援抵免）可消除這筆額外費用。拒絕回應會附帶一個抵免權杖，您在重試時回傳該權杖，重試便會以彷彿對話一直都在新模型上進行的方式計費。

只有當您自行建構重試時才需要閱讀本頁：透過原始 HTTP 或使用自訂重試邏輯。伺服器端備援與 SDK 中介軟體會自動套用備援抵免。如果您使用其中任一種，請跳過本頁。

拒絕與備援涵蓋如何偵測拒絕以及選擇備援方式。若您對快取讀取與快取寫入這些術語感到陌生，提示快取有相關說明。

基本流程

  1. 使用 beta 標頭選擇加入

    傳送可能被拒絕的請求時，附上 anthropic-beta: fallback-credit-2026-07-01 標頭。server-side-fallback-2026-07-01 標頭也會提供相同的欄位，而較早的 fallback-credit-2026-06-01 標頭仍被接受，並提供相同的欄位。

  2. 從拒絕回應中讀取兩個欄位

    發生拒絕時，stop_details 包含兩個欄位：

    • fallback_credit_token： 代表抵免的不透明字串。
    • fallback_has_prefill_claim： 一個布林值，告訴您應使用哪種重試主體形式。

    當該拒絕沒有可用的抵免時，兩者皆為 null。

  3. 建構重試

    從被拒絕的請求主體開始。將 model 設為備援模型，並將權杖加入為頂層的 fallback_credit_token 參數。從下表中選擇主體形式。

  4. 使用相同的標頭傳送重試

    使用相同的 fallback-credit-2026-07-01 beta 標頭傳送重試。重試需要該標頭才能兌換權杖。

fallback_has_prefill_claim 欄位告訴您重試是否可以接續被拒絕模型的部分輸出，而非從頭開始：

fallback_has_prefill_claim重試主體
true被拒絕的請求主體（不變），再附加一則 assistant 訊息，其 content 回傳被拒絕回應的 content。重試模型會從被拒絕模型停止的地方接續回應，且已完成的伺服器工具呼叫不會重新執行。
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，否則優先採用 continuation 形式
    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:
            # 退回使用未變更的 body，仍附帶 token
            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
            # token 本身遭拒：放棄該 token 並在不帶 token 的情況下重試。
            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 上處於 beta 階段。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. 接續被拒絕：重新傳送未變更的主體

    如果附加 assistant 訊息的重試被以 400 錯誤拒絕，請重新傳送未變更的被拒絕請求主體，仍附上權杖。

  2. 權杖被拒絕：移除權杖

    如果未變更的主體也被以 400 錯誤拒絕，且錯誤訊息中提及 fallback_credit_token，請在不附權杖的情況下重試。抵免會被放棄，但重試本身會成功送出。

參考

以下各節涵蓋邊緣案例與完整的兌換規則。大多數整合不需要這些內容。

後續步驟

拒絕與備援

偵測拒絕，並在伺服器端備援、SDK 中介軟體與手動重試之間做出選擇。

提示快取

快取讀取與快取寫入的計費方式。

停止原因與備援

每個 stop_reason 值及其處理方式。

SDK 中介軟體

自動套用備援抵免的 SDK 輔助工具。

Was this page helpful?