Credito di fallback
Evita di pagare due volte il costo della cache dei prompt quando ritenti su un altro modello una richiesta rifiutata.
Le cache dei prompt sono per modello. Quando un modello rifiuta una richiesta e tu ritenti su un altro modello, il prefisso della conversazione già memorizzato nella cache per il primo modello deve essere scritto da zero nella cache del nuovo modello. Le scritture in 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 ripeti 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 il credito di fallback automaticamente. Se usi uno dei due, salta questa pagina.
Rifiuti e fallback tratta il rilevamento dei rifiuti e la scelta di un approccio di fallback. Cache dei prompt spiega le letture dalla cache e le scritture in cache, se questi termini ti sono nuovi.
Il flusso di base
Aderisci con l'header beta
Invia la richiesta che potrebbe essere rifiutata con l'header
anthropic-beta: fallback-credit-2026-07-01. Anche l'headerserver-side-fallback-2026-07-01concede gli stessi campi, e il precedente headerfallback-credit-2026-06-01resta accettato e concede gli stessi campi.Leggi due campi dal rifiuto
In caso di rifiuto,
stop_detailsinclude due campi:fallback_credit_token: una stringa opaca che rappresenta il credito.fallback_has_prefill_claim: un booleano che ti indica quale forma del corpo del nuovo tentativo usare.
Entrambi sono
nullquando non è disponibile alcun credito per il rifiuto.Costruisci il nuovo tentativo
Parti dal corpo della richiesta rifiutata. Imposta
modelsul modello di fallback e aggiungi il token come parametro di primo livellofallback_credit_token. Scegli la forma del corpo dalla tabella seguente.Invia il nuovo tentativo con lo stesso header
Invia il nuovo tentativo con lo stesso header beta
fallback-credit-2026-07-01. Il nuovo tentativo ha bisogno dell'header per riscattare il token.
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:
fallback_has_prefill_claim | Corpo del nuovo tentativo |
|---|---|
true | Il corpo della richiesta rifiutata, invariato, più un messaggio assistant aggiunto in coda il cui content ripete il content della risposta rifiutata. Il modello del nuovo tentativo continua la risposta dal punto in cui il modello che ha rifiutato si è fermato, e le chiamate a strumenti server completate non vengono rieseguite. |
false | Il corpo della richiesta rifiutata, invariato. |
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 viene respinto, l'esempio degrada lungo la scala dei rifiuti: la sequenza di forme di retry progressivamente più semplici trattata 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 body 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: rinunciavi 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 emettono 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. Per Claude Fable 5.1 e Claude Fable 5, questi sono Claude Opus 4.8 (claude-opus-4-8) e Claude Opus 5 (claude-opus-5).
Sulla Claude API e su Claude Platform su AWS, l'elenco dei target è pubblicato come allowed_fallback_models nella voce di ciascun modello nella Models API quando è impostato l'header beta server-side-fallback-2026-07-01. L'elenco non è ancora visibile con il solo header fallback-credit-*. Non è esposto su Amazon Bedrock, Google Cloud o Microsoft Foundry.
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, ad esempio perché la cache del modello del nuovo tentativo era già calda.
Quando un nuovo tentativo viene respinto
La maggior parte dei nuovi tentativi riscatta il credito al primo colpo. Quando ciò non accade, l'API restituisce un errore 400 che ti indica cosa provare dopo.
Continuazione respinta: reinvia il corpo invariato
Se il nuovo tentativo che aggiunge il messaggio assistant viene respinto con un errore 400, reinvia il corpo della richiesta rifiutata invariato, sempre con il token.
Token respinto: elimina il token
Se anche il corpo invariato viene respinto con un errore 400 il cui messaggio cita
fallback_credit_token, ritenta senza il token. Il credito viene perso, ma il nuovo tentativo in sé va a buon fine.
Questo rifiuto è transitorio, non un verdetto sulla forma del tuo nuovo tentativo. Ritenta la stessa richiesta, con lo stesso token, entro la finestra di cinque minuti del token. Non passare al gradino successivo della scala.
Riferimento
Le sezioni seguenti trattano i casi limite e le regole complete di riscatto. La maggior parte delle integrazioni non ne ha bisogno.
Il riscatto confronta il nuovo tentativo con la richiesta rifiutata. Ogni campo che dà forma al prompt deve corrispondere esattamente. I campi che non danno forma al prompt possono cambiare nel nuovo tentativo.
| Regola | Campi |
|---|---|
| Devono corrispondere esattamente | system, messages, tools, tool_choice, thinking e cache_control, più output_config, mcp_servers, context_management e container quando li usi |
| Possono cambiare nel nuovo tentativo | model, max_tokens, stop_sequences, temperature, top_p, top_k, stream, metadata e service_tier |
La forma di continuazione (fallback_has_prefill_claim: true) è l'unica eccezione alla corrispondenza di messages: aggiunge esattamente un messaggio assistant alla fine di messages.
Non rimuovere i blocchi thinking o redacted_thinking dai turni precedenti nel nuovo tentativo, anche se un normale retry senza token di solito li rimuove. Il corpo deve corrispondere alla richiesta rifiutata, e il server gestisce quei blocchi da sé.
Invia nel nuovo tentativo gli stessi header anthropic-beta della richiesta rifiutata. Un header beta presente in una delle due richieste ma non nell'altra può far fallire la corrispondenza anche quando i corpi sono identici. L'errore 400 risultante riporta lo stesso messaggio request body ... does not match di una differenza nel corpo, quindi è facile scambiare una differenza negli header per un problema del corpo. In particolare, non aggiungere né rimuovere header beta in base al modello a cui è destinata la richiesta.
Due famiglie di header sono esenti dalla corrispondenza, a beneficio del nuovo tentativo:
server-side-fallback-*: un nuovo tentativo deve eliminare il parametrofallbacks, ed eliminare questo header insieme ad esso non causa una mancata corrispondenza.fallback-credit-*: mantieni questo header in entrambe le richieste. Il nuovo tentativo ne ha bisogno per riscattare il token.
Il campo è null solo quando anche il token è null, quindi un valore che osservi mentre possiedi un token non è mai null. Può comunque essere assente (None negli SDK tipizzati) su Amazon Bedrock, Google Cloud e Microsoft Foundry mentre il loro supporto per il campo viene distribuito. In quel caso, tratta la forma del nuovo tentativo come sconosciuta piuttosto che come false. Prova prima la forma con il messaggio assistant aggiunto, e affidati alla gestione dei rifiuti in Quando un nuovo tentativo viene respinto, che ricade sul corpo invariato.
Quando il token di un rifiuto supporta la forma di continuazione, il content della risposta contiene solo l'output del modello stesso, e la spiegazione del rifiuto viene fornita in stop_details.explanation. Puoi quindi ripetere content nel messaggio assistant aggiunto così com'è.
Potrebbero comunque essere necessari due aggiustamenti prima dell'invio:
- Se il blocco finale che invii è un blocco
text, rimuovi i suoi spazi bianchi finali. - Ometti qualsiasi blocco
tool_uselato client che non abbia untool_resultcorrispondente.
Se il contenuto ripetuto include un blocco fallback proveniente da un precedente fallback lato server, mantieni il blocco esattamente dove appariva. È accettato in qualsiasi richiesta senza un header beta. L'API usa la sua posizione per validare i blocchi thinking intorno ad esso, quindi una richiesta che ripete blocchi thinking da entrambi i lati di quel confine viene respinta se il blocco viene omesso o spostato.
Il token si riscatta solo dall'organizzazione e dal workspace che hanno ricevuto il rifiuto, anche su Microsoft Foundry. Su Amazon Bedrock e Google Cloud, che non hanno workspace, il token è invece legato all'identità del chiamante della piattaforma.
Il token scade cinque minuti dopo il rifiuto. Dopo di che, invia il nuovo tentativo senza di esso. Il token è inoltre stateless: il server non memorizza nulla al riguardo, e non esiste alcun endpoint per ispezionarlo o revocarlo.
Quando il rifiuto è arrivato dopo che gli strumenti server erano già stati eseguiti all'interno della richiesta, il token si riscatta solo continuando la risposta parziale. Questa restrizione è ciò che impedisce alle chiamate a strumenti completate di essere eseguite, e fatturate, di nuovo.
Una combinazione può quindi lasciare il token non riscattabile con nessuna delle due forme, quando entrambe le seguenti condizioni sono vere:
- La richiesta usava
output_config.formato untool_choiceche forza l'uso degli strumenti. Ciascuno dei due esclude la forma con il messaggio assistant aggiunto. - Il rifiuto è arrivato dopo che gli strumenti server erano stati eseguiti. Questo esclude il corpo invariato.
Se il nuovo tentativo con corpo invariato viene respinto con un errore 400 che dice che il token deve essere riscattato continuando la risposta parziale, scarta il token. Un nuovo tentativo senza di esso va a buon fine, ma riesegue e rifattura gli strumenti server completati. Esponi il costo o l'errore al tuo chiamante invece di ritentare silenziosamente.
Prossimi passi
Rileva i rifiuti e scegli tra fallback lato server, middleware dell'SDK e nuovo tentativo manuale.
Come vengono fatturate le letture dalla cache e le scritture in cache.
Ogni valore di stop_reason e come gestirlo.
L'helper dell'SDK che applica il credito di fallback automaticamente.
Was this page helpful?