Credito di fallback

Le cache dei prompt sono specifiche per modello. Quando Claude Fable 5 rifiuta una richiesta e riprovi 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, e le scritture in cache costano più delle letture dalla cache. Il credito di fallback elimina questo costo aggiuntivo: il rifiuto include un token di credito, tu riporti 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: con l'SDK Ruby o PHP, tramite HTTP diretto, o con 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 in cache se questi termini ti sono nuovi.

Il flusso di base

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

Esempio

L'esempio seguente effettua una richiesta che potrebbe essere rifiutata, riscatta il token di credito in un nuovo tentativo su Claude Opus 4.8 e degrada attraverso la scala di rifiuti descritta in Quando un nuovo tentativo viene rifiutato.

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}
    # Preferisci la forma di continuazione a meno che il claim non sia False
    if details.fallback_has_prefill_claim is not False:
        # Riproduci il contenuto del rifiuto, rimuovendo gli spazi finali da un
        # blocco di testo finale (il validatore del prefill lo rifiuta; il match lato
        # server tollera la modifica). Le richieste con strumenti omettono anche i blocchi
        # tool_use non accoppiati, poi rimuovono di nuovo gli spazi dopo le omissioni.
        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:
            # Ripiega sul corpo invariato, ancora con il 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
            # Il token stesso è stato rifiutato: rinunciaci 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, Claude Platform su AWS, Amazon Bedrock, Vertex AI e Microsoft Foundry. I token di credito restituiti nei risultati dei Message Batches non possono essere riscattati; il riscatto si applica solo alle richieste dirette alla Messages API.

Il modello del nuovo tentativo deve essere uno dei target di fallback consentiti per il modello rifiutato. Al lancio, il target consentito per Claude Fable 5 è Claude Opus 4.8 (claude-opus-4-8).

Verificare che il credito sia stato applicato

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

Quando un nuovo tentativo viene rifiutato

La maggior parte dei nuovi tentativi riscatta il credito al primo colpo. Quando ciò non accade, l'API restituisce un errore 400 che indica cosa provare dopo.

Riferimento

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

Passaggi successivi