Credito di fallback

Le cache dei prompt sono per modello. Quando Claude Fable 5 rifiuta una richiesta e ritenti su un altro modello, il prefisso della conversazione che era già stato memorizzato nella cache per Claude Fable 5 deve essere scritto da zero nella cache del nuovo modello. Le scritture nella cache costano più delle letture dalla cache. Il "fallback credit" (credito di fallback) elimina quel costo aggiuntivo. Il rifiuto contiene un token di credito, tu riproponi il token nel nuovo tentativo, e il nuovo tentativo viene fatturato come se la conversazione fosse stata sul nuovo modello fin dall'inizio.

Questa pagina ti serve solo quando costruisci tu stesso il nuovo tentativo: tramite HTTP grezzo o con una logica di retry personalizzata. Il fallback lato server e il middleware dell'SDK applicano automaticamente il credito di fallback. Se usi uno dei due, salta questa pagina.

Rifiuti e fallback spiega come rilevare i rifiuti e scegliere un approccio di fallback. Cache dei prompt spiega le letture e le scritture nella cache se questi termini sono nuovi per te.



Il flusso di base

Il campo fallback_has_prefill_claim ti indica se il nuovo tentativo può continuare l'output parziale del modello che ha rifiutato invece di ricominciare da capo:



Esempio

L'esempio seguente effettua una richiesta che potrebbe essere rifiutata e riscatta il token di credito in un nuovo tentativo su Claude Opus 4.8. Quando un tentativo di retry viene respinto, l'esempio degrada attraverso la scala dei respingimenti: la sequenza di forme di retry progressivamente più semplici descritta in Quando un nuovo tentativo viene respinto.

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}
    # Preferisci la forma di continuazione a meno che il claim non sia 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:
            # Ripiega sul corpo invariato, sempre con il 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
            # Il token stesso è stato rifiutato: rinuncia ad esso e riprova senza.
            response = send("claude-opus-4-8", request)

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



Dove funziona

Il credito di fallback è in beta sulla Claude API, Amazon Bedrock, Claude Platform su AWS, Google Cloud e Microsoft Foundry. I rifiuti nei Message Batches non generano token di credito, e il riscatto si applica solo alle richieste dirette alla Messages API: un token passato in una richiesta batch viene accettato ma ignorato.

Il modello del nuovo tentativo deve essere uno dei target di fallback consentiti per il modello che ha rifiutato. I target consentiti di Claude Fable 5 sono Claude Opus 4.8 (claude-opus-4-8) e Claude Opus 5 (claude-opus-5).



Verificare che il credito sia stato applicato

Il rimborso è visibile nello usage del nuovo tentativo. Rispetto a quanto la stessa richiesta riporterebbe senza il token, cache_creation_input_tokens è più basso e cache_read_input_tokens è più alto della stessa quantità. Uno scostamento pari a zero significa che il token è stato onorato ma non c'era nulla da riprezzare, per esempio perché la cache del modello del nuovo tentativo era già calda.



Quando un nuovo tentativo viene respinto

La maggior parte dei nuovi tentativi viene riscattata al primo colpo. Quando uno non lo è, l'API restituisce un errore 400 che ti indica cosa provare dopo.



Riferimento

Le sezioni seguenti coprono i casi limite e le regole complete di riscatto. La maggior parte delle integrazioni non ne ha bisogno.



Prossimi passi