Rifiuti e fallback

Claude Fable 5 include classificatori di sicurezza che possono rifiutare una richiesta. Quando ciò accade, ricevi una risposta normale, non un errore, con stop_reason: "refusal". Di solito puoi comunque ottenere una risposta inviando la stessa richiesta a un altro modello Claude. Questa pagina mostra come riconoscere un rifiuto e come configurare quel nuovo tentativo.

Leggi questa pagina quando sviluppi con Claude Fable 5 e vuoi che le richieste rifiutate passino automaticamente a un altro modello. Si applica anche quando hai appena visto "refusal" in una risposta e vuoi sapere cosa fare dopo.

L'elenco completo dei valori di stop_reason si trova in Motivi di arresto e fallback. I dettagli su come vengono fatturate le richieste rifiutate, e su come evitare di pagare due volte per la cache dei prompt su un nuovo tentativo, si trovano in Credito di fallback. L'helper dell'SDK che racchiude tutto questo si trova in Middleware SDK. Per un esempio completo end-to-end, consulta il Cookbook su fallback e fatturazione.

La configurazione più semplice: specifica un modello di fallback nella richiesta e l'API gestisce il nuovo tentativo.

await client.beta.messages.create({
  model: "claude-fable-5",
  max_tokens: 1024,
  messages,
  betas: ["server-side-fallback-2026-06-01"],
  fallbacks: [{ model: "claude-opus-4-8" }]
});

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

Come si presenta 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. Il suo campo category indica l'area di policy che ha attivato il classificatore. Il suo campo explanation è una descrizione leggibile dall'utente; il testo non è stabile, quindi visualizzalo anziché analizzarlo. Entrambi i campi sono null quando il rifiuto non corrisponde a una categoria denominata, e 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à dello stream dopo un output parziale. In entrambi i casi, considera qualsiasi output parziale come incompleto e scartalo.

Scegliere un approccio di fallback

Ci sono tre modi per riprovare una richiesta rifiutata su un altro modello. Quello giusto dipende da dove stai eseguendo il codice e da quanto controllo ti serve.

Il fallback lato server e il middleware SDK applicano il credito di fallback per te, quindi hai bisogno di quella pagina solo quando costruisci tu stesso il retry.

Fallback lato server

Il fallback lato server riprova una richiesta rifiutata all'interno di una singola chiamata API. Specifichi fino a tre modelli di fallback e, quando Claude Fable 5 rifiuta, l'API esegue il modello successivo nella catena sulla stessa richiesta. Ricevi una sola risposta che indica il modello che ha risposto, così il tuo utente ottiene una risposta in un unico round trip.

Effettuare la richiesta

Specifica i modelli di fallback nel parametro fallbacks e invia l'header beta server-side-fallback-2026-06-01.

Alcune regole si applicano all'elenco fallbacks:

• 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 specifica un model e può sovrascrivere max_tokens e thinking solo per quel tentativo.
• La richiesta deve essere valida come richiesta diretta a ogni modello specificato. Se un modello di fallback non supporta una funzionalità usata dalla richiesta, l'API rifiuta la richiesta in anticipo.
• 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'è.

Cosa contiene la risposta

La risposta è simile a qualsiasi altro messaggio, con due aggiunte:

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

In caso di rifiuto prima di qualsiasi output, il blocco fallback è il primo blocco di contenuto:

{
  "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 rifiutato appare come una voce message ordinaria, e il modello che ha servito il turno appare come una voce fallback_message. Se ogni modello nella catena rifiuta, la risposta è il rifiuto dell'ultimo modello, con una voce message per ogni passaggio precedente e una voce fallback_message per l'ultimo.

Continuare la conversazione

Al turno successivo, rinvia 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 rifiutato ha prodotto prima del passaggio di consegne; la tabella seguente indica quali mantenere e quali eliminare quando riporti 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. 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 rifiutato. Quando il rifiuto avviene a metà output, il blocco di contenuto aperto si chiude, il blocco fallback (una coppia ordinaria content_block_start e content_block_stop senza delta) segna il confine, e il modello di fallback continua 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. Nel caso a metà output message_start ha già indicato il modello richiesto, quindi leggi il modello che serve dalla proprietà to.model del blocco fallback e dalla voce fallback_message in usage.iterations del message_delta finale.

In una richiesta non in streaming, un rifiuto a metà output si comporta diversamente: la risposta omette l'output parziale del modello che ha rifiutato, 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 rifiutato e i suoi token di output appaiono comunque in usage.iterations.

Fallback lato client con il middleware SDK

Gli SDK TypeScript, Python, Go, Java e C# includono 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 riprovano quindi automaticamente le richieste rifiutate, su qualsiasi piattaforma. Il middleware invia anche l'header beta fallback-credit-2026-06-01 su ogni richiesta che gestisce, così i nuovi tentativi vengono ritariffati senza configurazione per richiesta.

Configurazione

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

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.
• La risposta di rifiuto originale viene restituita solo quando ogni modello nell'elenco ha rifiutato. Il middleware non solleva un errore per essa.
• I blocchi di thinking di Claude Fable 5 vengono gestiti per te: il middleware li rimuove dal nuovo tentativo e li gestisce nella cronologia della conversazione nelle richieste successive.
• Le risposte servite tramite il middleware includono un blocco di contenuto fallback a ogni confine tra modelli, come le risposte di 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 rimangono ancorate ad esso anziché interrogare di nuovo un modello che ha rifiutato.

Rifiuti nei Message Batch

Una richiesta rifiutata in un Message Batch ritorna come result.type: "succeeded" con stop_reason: "refusal". Il campo stop_details può essere null nei risultati batch, quindi rileva i rifiuti controllando direttamente stop_reason.

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

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

Errori comuni

• Riprova su un modello diverso. Rinviare una richiesta rifiutata allo stesso modello di solito produce un altro rifiuto. Indirizza il nuovo tentativo al modello di fallback.
• Imposta un budget di retry per richiesta, non per turno o per sessione. Un singolo turno può produrre diversi rifiuti, ad esempio un agente più i suoi sub-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 sub-agenti il loro fallback. Il parametro fallbacks non si propaga nelle 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 toggle globale possono desincronizzarsi e lasciare silenziosamente una richiesta non protetta. Quando non puoi confermare che il fallback è attivo, configuralo anziché presumere che lo sia.
• Strumenta i rifiuti come segnale a sé stante. Un rifiuto è un HTTP 200, quindi il monitoraggio basato su tassi di errore o risposte 5xx non lo vede mai. Emetti un evento per rifiuto e uno per risposta servita dal fallback (la voce fallback_message in segna quest'ultima), poi imposta un alert sulla differenza tra i due conteggi.

Passaggi successivi