Rifiuti e fallback

Claude Fable 5.1, Claude Fable 5 e Claude Opus 5 includono classificatori di sicurezza che possono declinare una richiesta. Quando ciò accade, ricevi una risposta normale, non un errore, con stop_reason: "refusal". Il suo stop_details.category indica l'area di policy (vedi Come appare un rifiuto). Di solito puoi comunque ottenere una risposta inviando la stessa richiesta a un altro modello Claude. Questa pagina ti mostra come riconoscere un "refusal" (rifiuto) e come configurare quel nuovo tentativo.

Leggi questa pagina quando sviluppi su uno qualsiasi di questi modelli e vuoi che le richieste declinate passino automaticamente a un altro modello. Si applica anche quando hai visto "refusal" in una risposta e vuoi sapere cosa fare dopo.

Pagine correlate:

• Motivi di arresto e fallback: l'elenco completo dei valori di stop_reason.
• Credito di fallback: come evitare di pagare due volte il costo della cache dei prompt quando costruisci tu stesso il nuovo tentativo.
• Middleware SDK: l'helper SDK che racchiude tutto questo.
• Cookbook su fallback e fatturazione: un esempio completo end-to-end.

La configurazione più semplice, in beta sulla Claude API: imposta fallbacks su "default", e l'API ritenta una richiesta declinata sul modello di fallback che Anthropic raccomanda per la sua categoria di rifiuto. Per le categorie senza un fallback raccomandato, il rifiuto rimane valido.

client = Anthropic()

response = client.beta.messages.create(
    model="claude-fable-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
    fallbacks="default",
    betas=["server-side-fallback-2026-07-01"],
)
print(response.model)

Le sezioni seguenti descrivono cosa contiene una risposta di rifiuto, quando usare il fallback lato server o lato client e come viene fatturato ciascuno.

Come appare un rifiuto

Un rifiuto è una risposta HTTP 200 riuscita con stop_reason: "refusal":

{
  "id": "msg_01XFUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "model": "claude-fable-5",
  "content": [],
  "stop_reason": "refusal",
  "stop_details": {
    "type": "refusal",
    "category": "cyber",
    "explanation": "This request was declined because it could enable cyber harm."
  },
  "usage": {
    "input_tokens": 412,
    "output_tokens": 0
  }
}

L'oggetto stop_details spiega il rifiuto:

• category: indica l'area di policy che ha attivato il classificatore.
• explanation: una descrizione leggibile. Il testo non è stabile, quindi visualizzalo anziché analizzarlo.
• recommended_model: presente solo nelle richieste che impostano fallbacks (fallback lato server, beta). Indica un modello su cui ritentare direttamente quando l'API ha saltato il tentativo di fallback (ad esempio, il modello di fallback era soggetto a limite di velocità), ed è null altrimenti. È un suggerimento, non una garanzia.
• category ed explanation sono entrambi null quando il rifiuto non corrisponde a una categoria denominata. Quel null è un valore normale e permanente, non un segnaposto.
• stop_details stesso è null per ogni motivo di arresto diverso da refusal.

Un rifiuto può arrivare prima di qualsiasi output, oppure a metà streaming dopo un output parziale. In entrambi i casi, tratta qualsiasi output parziale come incompleto e scartalo.

Scegliere un approccio di fallback

Esistono tre modi per ritentare una richiesta rifiutata su un altro modello. Quello giusto dipende da dove stai eseguendo e da quanto controllo ti serve.

Il fallback lato server e il middleware SDK applicano il credito di fallback per te. Hai bisogno della pagina Credito di fallback solo quando costruisci tu stesso il nuovo tentativo.

Fallback lato server

Il fallback lato server ritenta una richiesta rifiutata all'interno di una singola chiamata API. Nella modalità predefinita, quando il modello primario declina e la categoria di rifiuto ha un fallback raccomandato, l'API esegue la stessa richiesta sul modello che Anthropic raccomanda per quella categoria. Puoi invece indicare fino a tre modelli di fallback a tua scelta. In entrambi i casi, ricevi una sola risposta che indica il modello che ha risposto, così il tuo utente ottiene una risposta in un solo round trip.

Effettuare la richiesta

Imposta il parametro fallbacks sulla stringa "default" e invia l'header beta server-side-fallback-2026-07-01. L'API applica quindi il routing predefinito definito dal server per il modello richiesto, che seleziona un modello di fallback raccomandato in base alla categoria di rifiuto riportata dal classificatore, così le richieste rifiutate vengono servite senza che tu debba mantenere un elenco di modelli man mano che le raccomandazioni cambiano.

Il routing predefinito non provoca mai il rifiuto anticipato per immagine sovradimensionata per modelli che non hai scelto: un modello instradato che ridimensionerebbe un'immagine contrassegnata con "oversized_image": "error" viene invece escluso dal routing, così un'immagine contrassegnata non viene mai servita ridimensionata.

client = Anthropic()

response = client.beta.messages.create(
    model="claude-fable-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
    fallbacks="default",
    betas=["server-side-fallback-2026-07-01"],
)

# Una voce fallback_message in usage.iterations indica che è stato eseguito un modello di fallback;
# abbinala a stop_reason per confermare che il fallback abbia fornito la risposta.
fallback_ran = any(
    iteration.type == "fallback_message"
    for iteration in response.usage.iterations or []
)
served_by_fallback = fallback_ran and response.stop_reason != "refusal"

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

Anthropic definisce le salvaguardie per ciascun modello individualmente e per ciascuna categoria di policy, in linea con le capacità del modello: a seconda della categoria, una richiesta segnalata può ricadere su un modello meno capace oppure essere declinata. La modalità "default" codifica per te queste raccomandazioni per modello e per categoria, così una richiesta rifiutata viene ritentata sul modello che Anthropic raccomanda per quella categoria. I fallback sono visibili in entrambi i casi: la risposta indica il modello che l'ha servita, e il blocco di contenuto fallback segna il passaggio di consegne.

Il routing viene applicato lato server e non è pubblicato per modello sulla Models API. Per vedere quale modello ha servito una richiesta rifiutata, controlla il campo model di primo livello della risposta e cerca una voce fallback_message in usage.iterations, come fanno gli esempi di questa pagina.

Solo un rifiuto del classificatore di sicurezza attiva il fallback. Un limite di velocità, un sovraccarico o un errore del server sul modello richiesto ti viene restituito così com'è.

Indicare i propri modelli di fallback

Invece del routing predefinito, puoi impostare fallbacks su un elenco di fino a tre modelli. Quando il modello richiesto declina, l'API esegue il modello successivo nella catena sulla stessa richiesta. Usa questa forma quando vuoi controllare esattamente quali modelli servono le richieste rifiutate, ad esempio fissando un modello che la tua applicazione ha qualificato.

I modelli di fallback indicati contano ai fini del controllo delle immagini sovradimensionate: una richiesta il cui blocco immagine imposta "oversized_image": "error" viene controllata in anticipo rispetto al modello richiesto e a ogni fallback indicato, viene rifiutata se uno qualsiasi di essi ridimensionerebbe quell'immagine, e la dimensione di ridimensionamento riportata nel rifiuto è adatta a tutti.

Le righe evidenziate sono l'unica differenza rispetto alla richiesta con routing predefinito.

client = Anthropic()

response = client.beta.messages.create(
    model="claude-fable-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
    fallbacks=[{"model": "claude-opus-4-8"}],
    betas=["server-side-fallback-2026-07-01"],
)
print(response.model)

All'elenco fallbacks si applicano alcune regole:

• Le voci vengono provate in ordine. Ciascuna deve essere distinta dalle altre voci e dal modello richiesto.
• Ciascuna voce deve essere uno dei target consentiti del modello richiesto. Con l'header beta impostato, quell'elenco è pubblicato come allowed_fallback_models nella voce del modello nella Models API.
• Ciascuna voce indica un model e può sovrascrivere max_tokens, thinking, output_config e speed solo per quel tentativo.
• La richiesta deve essere valida come richiesta diretta a ogni modello indicato. Se un modello di fallback non supporta una funzionalità usata dalla richiesta, l'API rifiuta la richiesta in anticipo.
• Come nella modalità predefinita, solo un rifiuto del classificatore di sicurezza attiva il fallback. Un limite di velocità, un sovraccarico o un errore del server sul modello richiesto ti viene restituito così com'è.
• Se un modello di fallback è soggetto a limite di velocità o sovraccarico, il tentativo di fallback non viene effettuato e viene invece restituito il rifiuto precedente. Lo stop_details.recommended_model del rifiuto indica allora un modello su cui ritentare direttamente. Dimensiona i limiti di velocità del modello di fallback per il volume di rifiuti che prevedi, altrimenti sotto carico i fallback degradano in rifiuti.

La risposta ha la stessa forma in entrambe le modalità: il modello che ha servito il turno compare nel campo model di primo livello, un blocco di contenuto fallback segna il passaggio di consegne, e usage.iterations registra ogni tentativo.

Cosa contiene la risposta

La risposta appare come qualsiasi altro messaggio, con due aggiunte:

• Il campo model di primo livello riporta il modello che ha prodotto il messaggio restituito, sia esso il modello richiesto o un fallback.
• Un blocco di contenuto fallback segna ogni punto in content in cui l'output di un modello cede il passo al successivo: {"type": "fallback", "from": {"model": ...}, "to": {"model": ...}}.
  • from.model riprende la stringa del modello che hai inviato quando l'hop che declina è il modello richiesto.
  • to.model è sempre l'ID risolto del modello che prosegue.

In caso di rifiuto prima di qualsiasi output, il blocco fallback è il primo blocco di contenuto. Ad esempio, quando il routing predefinito seleziona Claude Opus 4.8 per la categoria del rifiuto:

{
  "id": "msg_01XFUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "model": "claude-opus-4-8",
  "content": [
    {
      "type": "fallback",
      "from": { "model": "claude-fable-5" },
      "to": { "model": "claude-opus-4-8" }
    },
    { "type": "text", "text": "Hi! How can I help you today?" }
  ],
  "stop_reason": "end_turn",
  "stop_details": null,
  "usage": {
    "input_tokens": 412,
    "output_tokens": 264,
    "cache_read_input_tokens": 0,
    "cache_creation_input_tokens": 0,
    "iterations": [
      {
        "type": "message",
        "model": "claude-fable-5",
        "input_tokens": 535,
        "output_tokens": 0,
        "cache_read_input_tokens": 0,
        "cache_creation_input_tokens": 0
      },
      {
        "type": "fallback_message",
        "model": "claude-opus-4-8",
        "input_tokens": 412,
        "output_tokens": 264,
        "cache_read_input_tokens": 0,
        "cache_creation_input_tokens": 0
      }
    ]
  }
}

L'array usage.iterations registra ogni tentativo. Un modello che ha declinato compare come una normale voce message, e il modello che ha servito il turno compare come voce fallback_message. Se ogni modello nella catena declina, la risposta è il rifiuto dell'ultimo modello, con una voce message per ogni hop precedente e una voce fallback_message per l'ultimo.

Il routing persistente può inviare un turno successivo direttamente al modello di fallback. Un tale turno non contiene alcun blocco di contenuto fallback, perché nessun modello ha declinato quel turno. Identificalo dalla voce fallback_message in usage.iterations, dall'assenza di una voce message per il modello richiesto e dal campo model della risposta.

Continuare la conversazione

Al turno successivo, rimanda il contenuto dell'assistente così come l'hai ricevuto. Dopo un fallback a metà output, content può includere tipi di blocco che il modello che ha declinato ha prodotto prima del passaggio di consegne. La tabella seguente indica quali mantenere e quali eliminare quando riproponi il turno.

Streaming

In una richiesta in streaming, il nuovo tentativo avviene sullo stesso stream, e nulla di ciò che hai già ricevuto viene invalidato. Ciò che vedi dipende da quando avviene il rifiuto.

Quando il rifiuto avviene prima di qualsiasi output:

• message_start indica il modello di fallback, e il blocco fallback è il primo blocco di contenuto.
• Poiché message_start attende l'avvio del tentativo di fallback, il tempo al primo byte include il tentativo declinato.

Quando il rifiuto avviene a metà output:

• Il blocco di contenuto aperto si chiude, e il blocco fallback (una normale coppia content_block_start e content_block_stop senza delta) segna il confine.
• Il modello di fallback prosegue dall'output parziale. Solo i blocchi text dell'output parziale vengono passati al modello di fallback come contesto. Gli altri tipi di blocco rimangono in content.
• message_start ha già indicato il modello richiesto, quindi leggi il modello che ha servito dal to.model del blocco fallback e dalla voce fallback_message in usage.iterations dell'ultimo message_delta.

Risposte non in streaming

In una richiesta non in streaming, un rifiuto a metà output si comporta diversamente: la risposta omette l'output parziale del modello declinato, e il modello di fallback risponde da zero. Il risultato appare come un rifiuto prima di qualsiasi output, con il blocco fallback per primo. Il tentativo declinato e i suoi token di output compaiono comunque in usage.iterations.

Fatturazione e limiti di velocità

Un tentativo che ha declinato prima di produrre qualsiasi output non viene fatturato: i suoi token sono riportati nella sua voce usage.iterations ma non addebitati. Ogni tentativo che ha prodotto output, incluso uno che ha declinato a metà della sua risposta, viene fatturato separatamente alle tariffe del modello che lo ha eseguito. L'array usage.iterations è il registro per tentativo di ciò che ti viene fatturato. I conteggi usage di primo livello descrivono solo il tentativo che ha prodotto il messaggio restituito. I token di modelli diversi non vengono mai sommati in un unico campo.

Ogni tentativo eseguito, incluso uno che ha declinato, conta ai fini dei limiti di velocità del proprio modello.

Routing persistente

Dopo che una conversazione è passata al fallback, l'API registra quale modello l'ha servita. Le richieste successive per quella conversazione che includono fallbacks vanno direttamente a quel modello di fallback, senza eseguire il modello richiesto. Questo evita di pagare a ogni turno un tentativo che verrebbe prevedibilmente declinato di nuovo.

Alcune proprietà della decisione di routing:

• Viene conservata per circa 1 ora ed è limitata alla tua organizzazione.
• Viene memorizzata come hash del contenuto del prefisso della conversazione più il modello che l'ha servita. Il contenuto dei messaggi in sé non viene memorizzato.
• È best-effort, quindi il tuo codice deve gestire il caso in cui il modello richiesto venga provato di nuovo in qualsiasi momento.

Il routing persistente si applica sia alle richieste in streaming sia a quelle non in streaming. In una richiesta in streaming, la decisione di routing viene presa prima dell'apertura dello stream, quindi il campo model dell'evento message_start contiene già l'ID del modello di fallback.

Fallback lato client con il middleware SDK

Ogni SDK Anthropic include un middleware di fallback per i rifiuti. Lo configuri una volta sul client con il tuo elenco di modelli di fallback. Le chiamate tramite client.beta.messages ritentano quindi automaticamente le richieste rifiutate, su qualsiasi piattaforma. Il middleware invia inoltre l'header beta fallback-credit-2026-07-01 su ogni richiesta che gestisce, così i nuovi tentativi vengono riprezzati senza configurazione per richiesta.

Configurazione

Passa il middleware al costruttore del client e condividi una singola istanza di BetaFallbackState tra le richieste di una conversazione.

from anthropic import Anthropic, BetaFallbackState, BetaRefusalFallbackMiddleware

# In caso di rifiuto, il middleware riprova con il modello di fallback indicato e
# invia automaticamente l'header beta fallback-credit a ogni richiesta che gestisce.
client = Anthropic(
    middleware=[BetaRefusalFallbackMiddleware([{"model": "claude-opus-4-8"}])],
)

state = BetaFallbackState()  # pins follow-ups to the model that accepted

# Streaming: in caso di rifiuto il middleware riprova con il modello di fallback e
# innesta i suoi eventi nello stream aperto.
with (
    state,
    client.beta.messages.stream(
        max_tokens=1024,
        model="claude-fable-5",
        messages=[{"role": "user", "content": "Hello, Claude"}],
    ) as stream,
):
    for text in stream.text_stream:
        print(text, end="", flush=True)
    final_message = stream.get_final_message()
print(f"\nserved by: {final_message.model}")

# Non-streaming: riutilizzare lo stato mantiene la conversazione fissata.
with state:
    message = client.beta.messages.create(
        max_tokens=1024,
        model="claude-fable-5",
        messages=[{"role": "user", "content": "Hello, Claude"}],
    )
print(f"served by: {message.model}")

Come si comporta

• I nuovi tentativi percorrono il tuo elenco di fallback in ordine. Un modello di fallback che a sua volta rifiuta passa la richiesta alla voce successiva.
• Quando ogni modello nell'elenco ha declinato, il middleware restituisce il rifiuto finale (la risposta di rifiuto dell'ultimo modello) anziché sollevare un errore.
• I blocchi di pensiero di Claude Fable 5.1 o Claude Fable 5 passano invariati. Ogni nuovo tentativo reinvia il corpo della tua richiesta originale, e gli unici blocchi che il middleware rimuove dalla cronologia della conversazione nelle richieste successive sono i blocchi di confine fallback che ha aggiunto esso stesso. Il modello di fallback non può leggere i blocchi di Claude Fable 5.1, che sono preservati solo per quel modello o uno più recente, quindi l'API li elimina.
• Le risposte servite tramite il middleware includono un blocco di contenuto fallback a ogni confine tra modelli, come le risposte del fallback lato server. Il middleware gestisce quei blocchi per te nelle richieste successive.
• Il modello che ha accettato viene registrato in BetaFallbackState, così le richieste successive che condividono lo stato restano fissate su di esso anziché richiedere nuovamente a un modello che ha rifiutato.

Scrivere il nuovo tentativo da soli

Su HTTP grezzo o con logica di retry personalizzata, implementa il pattern che il middleware racchiude:

1. 1

   Rileva il rifiuto

   Controlla la risposta per stop_reason: "refusal".

2. 2

   Reinvia su un modello di fallback

   Invia la stessa richiesta con model impostato su un modello di fallback, come Claude Opus 4.8. Un altro modello può normalmente servire una richiesta che Claude Fable 5.1 o Claude Fable 5 declina. Il modo in cui gestisci la cronologia della conversazione dipende dal fatto che tu riscatti o meno un credito di fallback:

   • Senza riscattare un credito: puoi lasciare al loro posto i blocchi thinking e redacted_thinking precedenti oppure rimuoverli per risparmiare token di input. Il modello di fallback non può usarli in nessun caso: ignora i blocchi di Claude Fable 5, e i blocchi di Claude Fable 5.1 sono preservati solo per quel modello o uno più recente, quindi l'API li elimina.
   • Riscattando un credito: invia il corpo invariato, perché il riscatto richiede una corrispondenza esatta. Il server gestisce i blocchi di pensiero del modello precedente in un riscatto, quindi non rimuoverli (vedi Campi che devono corrispondere alla richiesta rifiutata).
3. 3

   Resta sul modello di fallback

   Per le conversazioni multi-turno, continua a usare il modello di fallback per i turni successivi anziché tornare indietro.

Un nuovo tentativo manuale scrive da zero la cache dei prompt del modello di fallback, il che costa più della lettura di una cache esistente. Il credito di fallback rimborsa quel costo; riscattalo su ogni nuovo tentativo che costruisci tu stesso.

Rifiuti nei Message Batches

Una richiesta rifiutata in un Message Batch torna come result.type: "succeeded" con stop_reason: "refusal". I risultati batch contengono lo stesso oggetto stop_details delle risposte sincrone, quindi puoi rilevare i rifiuti tramite stop_reason o stop_details.type. Una differenza: i rifiuti batch non generano crediti di fallback, quindi stop_details su un risultato batch non include mai un fallback_credit_token.

Il fallback lato server non è disponibile per i batch (una richiesta batch che include fallbacks produce un risultato in errore per elemento). Per ritentare gli elementi batch rifiutati:

1. Raccogli gli elementi rifiutati dai risultati.
2. Rimuovi i blocchi di pensiero di Claude Fable 5.1 o Claude Fable 5 da eventuali cronologie multi-turno.
3. Reinviali su un modello di fallback come nuovo batch o come richieste dirette.

Errori comuni

• Ritenta su un modello diverso. Reinviare una richiesta rifiutata allo stesso modello di solito produce un altro rifiuto. Indirizza il nuovo tentativo al modello di fallback.
• Prevedi un budget di nuovi tentativi per richiesta, non per turno o per sessione. Un singolo turno può produrre diversi rifiuti, ad esempio un agente più i suoi sotto-agenti.
• Configura il fallback su ogni percorso di richiesta. Gestori di retry, rami di recupero errori e worker in background ne hanno tutti bisogno. Un gestore che riemette una richiesta senza fallback perde la protezione proprio sulle richieste che più probabilmente ne hanno bisogno.
• Dai alle chiamate dei sotto-agenti il proprio fallback. Il parametro fallbacks non si propaga alle chiamate al modello effettuate dall'interno dell'esecuzione degli strumenti.
• Rendi il fallback una proprietà della richiesta, non dello stato ambientale. Un flag condiviso, un valore di configurazione in cache o un interruttore globale possono perdere la sincronizzazione e lasciare silenziosamente una richiesta non protetta. Quando non puoi confermare che il fallback sia attivo, configuralo anziché presumere che sia attivo.
• Strumenta i rifiuti come segnale a sé. Un rifiuto è un HTTP 200, quindi il monitoraggio basato sui tassi di errore o sulle risposte 5xx non lo vede mai. Emetti un evento per ogni rifiuto e uno per ogni risposta servita tramite fallback (la voce fallback_message in usage.iterations contrassegna quest'ultima), quindi imposta un avviso sul divario tra i due conteggi.
• Dirama su stop_reason o stop_details.type, non su content o sui campi interni di stop_details. L'oggetto stop_details è sempre presente in un rifiuto, ma i suoi campi category ed explanation possono essere null. Controlla direttamente che stop_reason sia uguale a "refusal".

Prossimi passi