提示快取是依模型區分的。當 Claude Fable 5 拒絕一個請求,而您在另一個模型上重試時,原本已為 Claude Fable 5 快取的對話前綴必須從頭寫入新模型的快取中,而快取寫入的成本高於快取讀取。「Fallback credit」(備援額度)可消除這項額外成本:拒絕回應會附帶一個額度權杖,您在重試時回傳該權杖,重試的計費方式就會如同該對話一直都在新模型上進行一樣。
只有當您自行建構重試邏輯時才需要閱讀本頁:例如使用 Ruby 或 PHP SDK、透過原始 HTTP,或使用自訂重試邏輯。伺服器端備援和 SDK 中介軟體會自動套用備援額度。如果您使用其中任一種方式,可跳過本頁。
拒絕與備援說明如何偵測拒絕並選擇備援方法。如果您不熟悉快取讀取和快取寫入這些術語,提示快取有相關說明。
透過 beta 標頭啟用
發送可能被拒絕的請求時,附上 anthropic-beta: fallback-credit-2026-06-01 標頭。server-side-fallback-2026-06-01 標頭也會提供相同的欄位。
從拒絕回應中讀取兩個欄位
發生拒絕時,stop_details 會包含 fallback_credit_token(代表額度的不透明字串)以及 fallback_has_prefill_claim(一個布林值,告訴您該使用哪種重試主體格式)。當該次拒絕沒有可用的額度時,兩者皆為 null。
建構重試請求
從被拒絕的請求主體開始。將 model 設為備援模型,並將權杖新增為頂層的 fallback_credit_token 參數。依照下表選擇主體格式。
使用相同標頭發送重試
使用相同的 fallback-credit-2026-06-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, 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}
# 除非該宣告為 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:
# 退回至未變更的主體,仍保留該 token
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
# 該 token 本身遭拒:捨棄它並在不含它的情況下重試。
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、Vertex AI 和 Microsoft Foundry 上處於 beta 階段。在訊息批次處理結果中回傳的額度權杖無法兌換;兌換僅適用於直接的 Messages API 請求。
重試模型必須是被拒絕模型所允許的備援目標之一。在推出時,Claude Fable 5 允許的目標是 Claude Opus 4.8(claude-opus-4-8)。
退款會顯示在重試的 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?