提示快取(prompt cache)是依模型區分的。當 Claude Fable 5 拒絕一個請求,而您在另一個模型上重試時,已經為 Claude Fable 5 快取的對話前綴必須從頭寫入新模型的快取。快取寫入的成本高於快取讀取。「Fallback credit」(後備額度)消除了這項額外成本。拒絕回應會附帶一個額度權杖(credit token),您在重試時回傳該權杖,重試就會按照對話一開始就在新模型上進行的方式計費。
只有當您自行建構重試時才需要本頁面:透過原始 HTTP 或使用自訂重試邏輯。伺服器端後備和 SDK 中介軟體會自動套用後備額度。如果您使用其中任何一種,請跳過本頁面。
拒絕與後備涵蓋偵測拒絕和選擇後備方法。如果您不熟悉快取讀取和快取寫入這些術語,提示快取有相關說明。
使用 beta 標頭選擇加入
使用 anthropic-beta: fallback-credit-2026-07-01 標頭傳送可能被拒絕的請求。server-side-fallback-2026-07-01 標頭也會授予相同的欄位,而較早的 fallback-credit-2026-06-01 標頭仍然被接受並授予相同的欄位。
從拒絕回應中讀取兩個欄位
在拒絕回應中,stop_details 包含兩個欄位:
fallback_credit_token: 代表額度的不透明字串。fallback_has_prefill_claim: 一個布林值,告訴您要使用哪種重試主體形式。當該拒絕沒有可用的額度時,兩者都是 null。
建構重試
從被拒絕的請求主體開始。將 model 設定為後備模型,並將權杖新增為頂層的 fallback_credit_token 參數。從下表中選擇主體形式。
使用相同的標頭傳送重試
使用相同的 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、AWS 上的 Claude Platform、Google Cloud 和 Microsoft Foundry 上處於 beta 階段。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 錯誤拒絕,請重新傳送未變更的被拒絕請求主體,仍然帶著權杖。
權杖被拒絕:移除權杖
如果未變更的主體也被 400 錯誤拒絕,且錯誤訊息中提到 fallback_credit_token,請在不帶權杖的情況下重試。額度會被放棄,但重試本身會成功。
如果被拒絕的請求執行了伺服器工具,不帶權杖的重試會重新執行並重新計費這些工具。在這種情況下,請將 400 錯誤呈現給您的呼叫者,而不是退回到不帶權杖的重試。
以下各節涵蓋邊緣案例和完整的兌換規則。大多數整合不需要這些內容。
偵測拒絕並在伺服器端後備、SDK 中介軟體和手動重試之間做出選擇。
快取讀取和快取寫入如何計費。
每個 stop_reason 值及其處理方式。
自動套用後備額度的 SDK 輔助工具。
Was this page helpful?