提示缓存是按模型划分的。当 Claude Fable 5 拒绝一个请求而您在另一个模型上重试时,已经为 Claude Fable 5 缓存的对话前缀必须从头写入新模型的缓存。缓存写入的成本高于缓存读取。"Fallback credit"(回退额度)消除了这部分额外成本。拒绝响应会携带一个额度令牌,您在重试时回传该令牌,重试就会按照对话一直在新模型上进行的方式计费。
只有当您自行构建重试逻辑时才需要本页面:通过原始 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}
# 除非声明为 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 上处于 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 错误拒绝,请重新发送未更改的被拒绝请求体,仍然携带令牌。
令牌被拒绝:移除令牌
如果未更改的请求体也被一个消息中提及 fallback_credit_token 的 400 错误拒绝,请在不携带令牌的情况下重试。额度会被放弃,但重试本身可以通过。
如果被拒绝的请求执行了服务器工具,不携带令牌的重试会重新运行并重新计费这些工具。在这种情况下,请将 400 错误呈现给您的调用方,而不是降级到不携带令牌的重试。
以下各节涵盖边缘情况和完整的兑换规则。大多数集成不需要它们。
检测拒绝,并在服务端回退、SDK 中间件和手动重试之间做出选择。
缓存读取和缓存写入的计费方式。
每个 stop_reason 值及其处理方式。
自动应用回退额度的 SDK 辅助工具。
Was this page helpful?