提示缓存是按模型划分的。当 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:
# 回退到未更改的正文,仍保留该令牌
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、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?