• 消息
  • 托管智能体
  • 管理
Search...
⌘K
第一步
Claude 简介快速入门
使用 Claude 构建
功能概览使用消息 API停止原因与回退拒绝与回退回退额度
模型能力
扩展思考自适应思考努力程度任务预算(测试版)快速模式(研究预览)结构化输出引用流式传输消息批处理搜索结果流式传输拒绝多语言支持嵌入
工具
概览工具使用的工作原理教程:构建使用工具的智能体定义工具处理工具调用并行工具使用工具运行器(SDK)严格工具使用工具使用与提示缓存服务器工具故障排除网络搜索工具网页获取工具代码执行工具顾问工具记忆工具Bash 工具计算机使用工具文本编辑器工具
工具基础设施
工具参考管理工具上下文工具组合工具搜索编程式工具调用细粒度工具流式传输
上下文管理
上下文窗口压缩上下文编辑提示缓存对话中系统消息构建编排模式缓存诊断(测试版)令牌计数
处理文件
文件 APIPDF 支持图像与视觉
技能
概览快速入门最佳实践企业技能API 中的技能
MCP
远程 MCP 服务器MCP 连接器
云平台上的 Claude
Amazon BedrockAmazon Bedrock(旧版)AWS 上的 Claude PlatformMicrosoft FoundryVertex AI
Log in
回退额度
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...

Solutions

  • AI agents
  • Code modernization
  • Coding
  • Customer support
  • Education
  • Financial services
  • Government
  • Life sciences

Partners

  • Amazon Bedrock
  • Google Cloud's Vertex AI

Learn

  • Blog
  • Courses
  • Use cases
  • Connectors
  • Customer stories
  • Engineering at Anthropic
  • Events
  • Powered by Claude
  • Service partners
  • Startups program

Company

  • Anthropic
  • Careers
  • Economic Futures
  • Research
  • News
  • Responsible Scaling Policy
  • Security and compliance
  • Transparency

Learn

  • Blog
  • Courses
  • Use cases
  • Connectors
  • Customer stories
  • Engineering at Anthropic
  • Events
  • Powered by Claude
  • Service partners
  • Startups program

Help and security

  • Availability
  • Status
  • Support
  • Discord

Terms and policies

  • Privacy policy
  • Responsible disclosure policy
  • Terms of service: Commercial
  • Terms of service: Consumer
  • Usage policy
消息/使用 Claude 构建

回退积分

当您在另一个模型上重试被 Claude Fable 5 拒绝的请求时,避免重复支付提示缓存成本。

提示缓存是按模型划分的。当 Claude Fable 5 拒绝某个请求,而您在另一个模型上重试时,已经为 Claude Fable 5 缓存的对话前缀必须从头写入新模型的缓存,而缓存写入的成本高于缓存读取。"Fallback credit"(回退积分)可以消除这部分额外成本:拒绝响应会携带一个积分令牌,您在重试时回传该令牌,重试就会按照对话一直在新模型上进行的方式计费。

只有当您自行构建重试逻辑时才需要阅读本页:例如使用 Ruby 或 PHP SDK、通过原始 HTTP 调用,或使用自定义重试逻辑。服务器端回退和 SDK 中间件会自动应用回退积分。如果您使用其中任何一种方式,可以跳过本页。

拒绝与回退介绍了如何检测拒绝以及如何选择回退方式。如果您不熟悉缓存读取和缓存写入这些术语,请参阅提示缓存。

基本流程

  1. 1

    通过 beta 标头启用

    在发送可能被拒绝的请求时附带 anthropic-beta: fallback-credit-2026-06-01 标头。server-side-fallback-2026-06-01 标头同样会授予相同的字段。

  2. 2

    从拒绝响应中读取两个字段

    当请求被拒绝时,stop_details 会包含 fallback_credit_token(一个表示积分的不透明字符串)和 fallback_has_prefill_claim(一个布尔值,告诉您应使用哪种重试请求体结构)。当该拒绝没有可用积分时,两者均为 null。

  3. 3

    构建重试请求

    从被拒绝的请求体开始。将 model 设置为回退模型,并将令牌作为顶层 fallback_credit_token 参数添加。根据下表选择请求体结构。

  4. 4

    使用相同的标头发送重试请求

    使用相同的 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 错误,告诉您接下来应尝试什么。

  1. 1

    续写被拒绝:重新发送未更改的请求体

    如果追加了 assistant 消息的重试被 400 错误拒绝,请重新发送未更改的被拒绝请求体,仍然带上令牌。

  2. 2

    令牌被拒绝:移除令牌

    如果未更改的请求体也被 400 错误拒绝,且错误消息中提到了 fallback_credit_token,则在不带令牌的情况下重试。积分将被放弃,但重试本身会成功。

如果被拒绝的请求执行了服务器工具,不带令牌的重试会重新运行这些工具并重新计费。在这种情况下,请将 400 错误返回给您的调用方,而不是继续降级到不带令牌的重试。

参考

以下各节涵盖边缘情况和完整的兑换规则。大多数集成不需要这些内容。

后续步骤

拒绝与回退

检测拒绝,并在服务器端回退、SDK 中间件和手动重试之间进行选择。

提示缓存

缓存读取和缓存写入的计费方式。

停止原因与回退

每个 stop_reason 值及其处理方式。

SDK 中间件

自动应用回退积分的 SDK 辅助工具。

Was this page helpful?

  • 基本流程
  • 示例
  • 适用范围
  • 检查积分是否已应用
  • 当重试被拒绝时
  • 参考
  • 后续步骤