Crédito de fallback

Os caches de prompt são por modelo. Quando o Claude Fable 5 recusa uma solicitação e você tenta novamente em outro modelo, o prefixo da conversa que já estava em cache para o Claude Fable 5 precisa ser gravado do zero no cache do novo modelo. Gravações de cache custam mais do que leituras de cache. O "fallback credit" (crédito de fallback) remove 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: sobre HTTP bruto 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 cobre a detecção de recusas e a escolha de uma abordagem de fallback. Cache de prompt explica leituras de cache e gravações de cache se esses termos forem 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 a seguir faz uma solicitação que pode ser recusada e resgata o token de crédito em uma nova tentativa contra o Claude Opus 4.8. Quando uma tentativa de retry é rejeitada, o exemplo degrada através da escada de rejeição: a sequência de formatos de retry progressivamente mais simples coberta em Quando uma nova tentativa é rejeitada.

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}
    # Prefira a forma de continuação, a menos que a afirmação seja 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:
            # Recorra ao corpo inalterado, ainda com o token
            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
            # 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, Amazon Bedrock, Claude Platform na AWS, Google Cloud e Microsoft Foundry. Recusas em Message Batches não geram tokens de crédito, e o resgate se aplica apenas a solicitações diretas à Messages API: um token passado em uma solicitação de lote é aceito, mas ignorado.

O modelo da nova tentativa deve ser um dos alvos de fallback permitidos do modelo recusado. Os alvos permitidos do Claude Fable 5 são Claude Opus 4.8 (claude-opus-4-8) e Claude Opus 5 (claude-opus-5).



Verificando se o crédito foi aplicado

O reembolso é visível no usage da nova tentativa. Em comparação com o que a mesma solicitação reportaria sem o token, cache_creation_input_tokens é menor, e cache_read_input_tokens é maior na mesma quantidade. 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 é resgatada na primeira tentativa. Quando uma não é, 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