Crédito de fallback

Os caches de prompt são específicos por modelo. Quando o Claude Fable 5 recusa uma solicitação e você a repete em outro modelo, o prefixo da conversa que já estava em cache para o Claude Fable 5 precisa ser gravado no cache do novo modelo do zero, e gravações de cache custam mais do que leituras de cache. O crédito de fallback elimina esse custo extra: a recusa carrega um token de crédito, você ecoa o token na nova tentativa, e a nova tentativa é cobrada como se a conversa tivesse estado no novo modelo desde o início.

Você só precisa desta página quando constrói a nova tentativa por conta própria: no SDK de Ruby ou PHP, via HTTP puro, ou com lógica de retry personalizada. O fallback do lado do servidor e o middleware do SDK aplicam o crédito de fallback automaticamente. Se você usa qualquer um deles, pule esta página.

Recusas e fallback aborda como detectar recusas e escolher uma abordagem de fallback. Cache de prompt explica leituras de cache e gravações de cache, caso esses termos sejam novos para você.

O fluxo básico

O campo fallback_has_prefill_claim indica se a nova tentativa pode continuar a saída parcial do modelo recusado em vez de começar do zero:

Exemplo

O exemplo abaixo faz uma solicitação que pode ser recusada, resgata o token de crédito em uma nova tentativa contra o Claude Opus 4.8 e degrada através da escada de rejeição abordada em Quando uma nova tentativa é rejeitada.

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}
    # Prefira o formato de continuação, a menos que a afirmação seja False
    if details.fallback_has_prefill_claim is not False:
        # Ecoe o conteúdo da recusa, removendo espaços em branco finais de um
        # bloco de texto final (o validador de prefill o rejeita; a correspondência
        # do lado do servidor tolera a edição). Requisições com uso de ferramentas também
        # omitem blocos tool_use não pareados e removem espaços novamente após omissões.
        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:
            # Recorra ao corpo inalterado, ainda com o 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
            # O próprio token foi rejeitado: descarte-o e tente novamente sem ele.
            response = send("claude-opus-4-8", request)

print(json.dumps({"stop_reason": response.stop_reason, "model": response.model}))

Onde funciona

O crédito de fallback está em beta na Claude API, Claude Platform on AWS, Amazon Bedrock, Vertex AI e Microsoft Foundry. Tokens de crédito retornados em resultados de Message Batches não podem ser resgatados; o resgate se aplica apenas a solicitações diretas da Messages API.

O modelo da nova tentativa deve ser um dos alvos de fallback permitidos do modelo recusado. No lançamento, o alvo permitido do Claude Fable 5 é o Claude Opus 4.8 (claude-opus-4-8).

Verificando se o crédito foi aplicado

O reembolso é visível no usage da nova tentativa: cache_creation_input_tokens é menor, e cache_read_input_tokens é maior na mesma quantidade, do que a mesma solicitação reportaria sem o token. Uma diferença de zero significa que o token foi honrado, mas não havia nada para reprecificar, por exemplo porque o cache do modelo da nova tentativa já estava aquecido.

Quando uma nova tentativa é rejeitada

A maioria das novas tentativas resgata na primeira tentativa. Quando uma não resgata, a API retorna um erro 400 que indica o que tentar em seguida.

Referência

As seções abaixo cobrem casos extremos e as regras completas de resgate. A maioria das integrações não precisa delas.

Próximos passos