提示缓存是按模型划分的。当 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 | 被拒绝的请求体保持不变,并在末尾追加一条助手消息,其 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:
# 回退到未更改的正文,仍保留该令牌
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
# 令牌本身被拒绝:放弃它并在不带令牌的情况下重试。
response = send("claude-opus-4-8", request)
print(json.dumps({"stop_reason": response.stop_reason, "model": response.model}))回退额度目前在 Claude API、AWS 上的 Claude Platform、Amazon Bedrock、Google Cloud 和 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 错误,告知您下一步该尝试什么。
续写被拒绝:重新发送未更改的请求体
如果追加了助手消息的重试被拒绝并返回 400 错误,请重新发送未更改的被拒绝请求体,仍然附带令牌。
令牌被拒绝:移除令牌
如果未更改的请求体也被拒绝,且 400 错误消息中提到了 fallback_credit_token,请在不带令牌的情况下重试。额度将被放弃,但重试本身会成功。
如果被拒绝的请求执行了服务端工具,不带令牌的重试会重新运行这些工具并重新计费。在这种情况下,请将 400 错误返回给您的调用方,而不是直接降级到不带令牌的重试。
以下各节涵盖边缘情况和完整的兑换规则。大多数集成不需要这些内容。
检测拒绝,并在服务端回退、SDK 中间件和手动重试之间进行选择。
缓存读取和缓存写入的计费方式。
每个 stop_reason 值及其处理方式。
自动应用回退额度的 SDK 辅助工具。
Was this page helpful?