Refus et fallback

Claude Fable 5 et Claude Opus 5 incluent des classificateurs de sécurité qui peuvent décliner une requête. Lorsque cela se produit, vous recevez une réponse normale, et non une erreur, avec stop_reason: "refusal". Vous pouvez généralement toujours obtenir une réponse en envoyant la même requête à un autre modèle Claude. Cette page vous montre comment reconnaître un refus et comment configurer cette nouvelle tentative.

Lisez cette page lorsque vous développez sur Claude Fable 5 ou Claude Opus 5 et que vous souhaitez que les requêtes déclinées basculent automatiquement vers un autre modèle. Elle s'applique également lorsque vous venez de voir "refusal" dans une réponse et que vous voulez savoir quoi faire ensuite.

Pages connexes :

• Raisons d'arrêt et fallback : la liste complète des valeurs de stop_reason.
• Crédit de fallback : comment les requêtes refusées sont facturées, et comment éviter de payer deux fois la mise en cache des prompts lors d'une nouvelle tentative.
• Middleware du SDK : l'assistant du SDK qui encapsule tout cela.
• Cookbook sur le fallback et la facturation : un exemple complet de bout en bout.

La configuration la plus simple, en version bêta sur l'API Claude : définissez fallbacks sur "default", et l'API réessaie une requête déclinée sur le modèle de « fallback » (repli) qu'Anthropic recommande pour sa catégorie de refus. Pour les catégories sans fallback recommandé, le refus est maintenu.

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)

Les sections suivantes couvrent ce que contient une réponse de refus, quand utiliser le fallback côté serveur ou côté client, et comment chacun est facturé.



À quoi ressemble un refus

Un refus est une réponse HTTP 200 réussie avec 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'objet stop_details explique le refus :

• category : nomme le domaine de politique qui a déclenché le classificateur.
• explanation : une description lisible par un humain. Le texte n'est pas stable, affichez-le donc plutôt que de l'analyser.
• Les deux champs sont null lorsque le refus ne correspond à aucune catégorie nommée. Ce null est une valeur normale et permanente, pas un espace réservé.
• stop_details lui-même est null pour toute raison d'arrêt autre que refusal.

Un refus peut survenir avant toute sortie, ou en cours de flux après une sortie partielle. Dans les deux cas, traitez toute sortie partielle comme incomplète et supprimez-la.



Choisir une approche de fallback

Il existe trois façons de réessayer une requête refusée sur un autre modèle. La bonne approche dépend de l'endroit où vous exécutez votre application et du niveau de contrôle dont vous avez besoin.

Le fallback côté serveur et le middleware du SDK appliquent le crédit de fallback pour vous. Vous n'avez besoin de la page Crédit de fallback que lorsque vous construisez la nouvelle tentative vous-même.



Fallback côté serveur

Le fallback côté serveur réessaie une requête refusée au sein d'un seul appel API. Dans le mode par défaut, lorsque le modèle principal décline et que la catégorie de refus a un fallback recommandé, l'API exécute la même requête sur le modèle qu'Anthropic recommande pour cette catégorie. Vous pouvez à la place nommer jusqu'à trois modèles de fallback de votre choix (ci-dessous). Dans les deux cas, vous recevez une seule réponse qui nomme le modèle qui a répondu, de sorte que votre utilisateur obtient une réponse en un seul aller-retour.



Effectuer la requête

Définissez le paramètre fallbacks sur la chaîne "default" et envoyez l'en-tête bêta server-side-fallback-2026-07-01. L'API applique alors le routage par défaut défini côté serveur pour le modèle demandé, qui sélectionne un modèle de fallback recommandé en fonction de la catégorie de refus signalée par le classificateur, de sorte que les requêtes refusées sont servies sans que vous ayez à maintenir une liste de modèles à mesure que les recommandations évoluent.

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"],
)

# Une entrée fallback_message dans usage.iterations signifie qu'un modèle de repli a été exécuté ;
# associez-la à stop_reason pour confirmer que le repli a servi la réponse.
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 définit des garde-fous pour chaque modèle individuellement et pour chaque catégorie de politique, en fonction des capacités du modèle : selon la catégorie, une requête signalée peut basculer vers un modèle moins capable ou être déclinée. Le mode "default" encode ces recommandations par modèle et par catégorie pour vous, de sorte qu'une requête refusée est réessayée sur le modèle qu'Anthropic recommande pour cette catégorie. Les fallbacks sont visibles dans tous les cas : la réponse nomme le modèle qui l'a servie, et le bloc de contenu fallback marque le transfert.

Le routage est appliqué côté serveur et n'est pas publié par modèle sur l'API Models. Pour voir quel modèle a servi une requête refusée, vérifiez le champ model de premier niveau de la réponse et recherchez une entrée fallback_message dans usage.iterations, comme le font les exemples de cette page.

Seul un refus du classificateur de sécurité déclenche le fallback. Une limite de débit, une surcharge ou une erreur serveur sur le modèle demandé vous est renvoyée telle quelle.



Nommer vos propres modèles de fallback

Au lieu du routage par défaut, vous pouvez définir fallbacks sur une liste d'au maximum trois modèles. Lorsque le modèle demandé décline, l'API exécute le modèle suivant de la chaîne sur la même requête. Utilisez cette forme lorsque vous voulez contrôler exactement quels modèles servent les requêtes refusées, par exemple pour épingler un modèle que votre application a qualifié.

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)

Quelques règles s'appliquent à la liste fallbacks :

• Les entrées sont essayées dans l'ordre. Chacune doit être distincte des autres entrées et du modèle demandé.
• Chaque entrée doit être l'une des cibles autorisées du modèle demandé. Avec l'en-tête bêta défini, cette liste est publiée sous allowed_fallback_models dans l'entrée du modèle sur l'API Models.
• Chaque entrée nomme un model et peut remplacer max_tokens, thinking, output_config et speed pour cette tentative uniquement.
• La requête doit être valide en tant que requête directe vers chaque modèle nommé. Si un modèle de fallback ne prend pas en charge une fonctionnalité utilisée par la requête, l'API rejette la requête d'emblée.
• Comme pour le mode par défaut, seul un refus du classificateur de sécurité déclenche le fallback. Une limite de débit, une surcharge ou une erreur serveur sur le modèle demandé vous est renvoyée telle quelle.

La forme de liste explicite fonctionne également avec l'en-tête bêta server-side-fallback-2026-06-01 ; le mode "default" non.

La réponse a la même forme dans les deux modes : le modèle qui a servi le tour apparaît dans le champ model de premier niveau, un bloc de contenu fallback marque le transfert, et usage.iterations enregistre chaque tentative.



Ce que contient la réponse

La réponse ressemble à n'importe quel autre message, avec deux ajouts :

• Le champ model de premier niveau indique le modèle qui a produit le message renvoyé, qu'il s'agisse du modèle demandé ou d'un fallback.
• Un bloc de contenu fallback marque chaque point de content où la sortie d'un modèle cède la place au suivant : {"type": "fallback", "from": {"model": ...}, "to": {"model": ...}}.
  • from.model reprend la chaîne de modèle que vous avez envoyée lorsque le saut qui décline est le modèle demandé.
  • to.model est toujours l'ID résolu du modèle qui continue.

Lors d'un refus avant toute sortie, le bloc fallback est le premier bloc de contenu. Par exemple, lorsque le routage par défaut sélectionne Claude Opus 4.8 pour la catégorie du refus :

{
  "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
      }
    ]
  }
}

Le tableau usage.iterations enregistre chaque tentative. Un modèle qui a décliné apparaît comme une entrée message ordinaire, et le modèle qui a servi le tour apparaît comme une entrée fallback_message. Si chaque modèle de la chaîne décline, la réponse est le refus du dernier modèle, avec une entrée message pour chaque saut précédent et une entrée fallback_message pour le dernier.



Poursuivre la conversation

Au tour suivant, renvoyez le contenu de l'assistant tel que vous l'avez reçu. Après un fallback en cours de sortie, content peut inclure des types de blocs que le modèle qui a décliné a produits avant le transfert ; le tableau suivant indique lesquels conserver et lesquels supprimer lorsque vous renvoyez le tour.



Streaming

Sur une requête en streaming, la nouvelle tentative se produit sur le même flux, et rien de ce que vous avez déjà reçu n'est invalidé. Ce que vous voyez dépend du moment où le refus se produit.

Lorsque le refus se produit avant toute sortie :

• message_start nomme le modèle de fallback, et le bloc fallback est le premier bloc de contenu.
• Comme message_start attend le démarrage de la tentative de fallback, le temps jusqu'au premier octet inclut la tentative déclinée.

Lorsque le refus se produit en cours de sortie :

• Le bloc de contenu ouvert se ferme, et le bloc fallback (une paire ordinaire content_block_start et content_block_stop sans deltas) marque la frontière.
• Le modèle de fallback continue à partir de la sortie partielle. Seuls les blocs text de la sortie partielle sont transmis au modèle de fallback comme contexte ; les autres types de blocs restent dans content.
• message_start a déjà nommé le modèle demandé, lisez donc le modèle qui sert la requête à partir du to.model du bloc fallback et de l'entrée fallback_message dans usage.iterations du message_delta final.



Réponses sans streaming

Sur une requête sans streaming, un refus en cours de sortie se comporte différemment : la réponse omet la sortie partielle du modèle qui a décliné, et le modèle de fallback répond depuis le début. Le résultat ressemble à un refus avant toute sortie, avec le bloc fallback en premier. La tentative déclinée et ses tokens de sortie apparaissent tout de même dans usage.iterations.



Fallback côté client avec le middleware du SDK

Chaque SDK Anthropic inclut un middleware de fallback sur refus. Vous le configurez une fois sur le client avec votre liste de modèles de fallback. Les appels via client.beta.messages réessaient alors automatiquement les requêtes refusées, sur n'importe quelle plateforme. Le middleware envoie également l'en-tête bêta fallback-credit-2026-07-01 sur chaque requête qu'il gère, de sorte que les nouvelles tentatives sont retarifées sans configuration par requête.



Configuration

Passez le middleware au constructeur du client, et partagez une seule instance BetaFallbackState entre les requêtes d'une conversation.

from anthropic import Anthropic, BetaFallbackState, BetaRefusalFallbackMiddleware

# En cas de refus, le middleware réessaie sur le modèle de repli indiqué et
# envoie automatiquement l'en-tête bêta fallback-credit sur chaque requête qu'il traite.
client = Anthropic(
    middleware=[BetaRefusalFallbackMiddleware([{"model": "claude-opus-4-8"}])],
)

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

# Streaming : en cas de refus, le middleware réessaie sur le modèle de repli et
# insère ses événements dans le flux ouvert.
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 : réutiliser l'état maintient la conversation épinglée.
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}")



Comment il se comporte

• Les nouvelles tentatives parcourent votre liste de fallback dans l'ordre. Un modèle de fallback qui refuse lui-même passe la requête à l'entrée suivante.
• Lorsque chaque modèle de la liste a décliné, le middleware renvoie le refus final (la réponse de refus du dernier modèle) plutôt que de lever une erreur.
• Les blocs de réflexion de Claude Fable 5 passent sans modification : chaque nouvelle tentative renvoie le corps de votre requête d'origine, et les seuls blocs que le middleware retire de l'historique de conversation lors des requêtes ultérieures sont les blocs de frontière fallback qu'il a lui-même ajoutés.
• Les réponses servies via le middleware incluent un bloc de contenu fallback à chaque frontière de modèle, comme les réponses de fallback côté serveur. Le middleware gère ces blocs pour vous lors des requêtes ultérieures.
• Le modèle qui a accepté est enregistré dans BetaFallbackState, de sorte que les requêtes de suivi qui partagent l'état restent épinglées à celui-ci plutôt que de redemander à un modèle qui a refusé.



Refus dans les Message Batches

Une requête refusée dans un Message Batch revient comme result.type: "succeeded" avec stop_reason: "refusal". Les résultats de lot portent le même objet stop_details que les réponses synchrones, vous pouvez donc détecter les refus via stop_reason ou stop_details.type. Une différence : les refus de lot n'émettent pas de crédits de fallback, donc stop_details sur un résultat de lot n'inclut jamais de fallback_credit_token.

Le fallback côté serveur n'est pas disponible pour les lots (une requête de lot qui inclut fallbacks produit un résultat en erreur par élément). Pour réessayer les éléments de lot refusés :

1. Collectez les éléments refusés à partir des résultats.
2. Retirez les blocs de réflexion de Claude Fable 5 de tout historique multi-tours.
3. Soumettez-les à nouveau sur un modèle de fallback en tant que nouveau lot ou en tant que requêtes directes.



Pièges courants

• Réessayez sur un modèle différent. Renvoyer une requête refusée au même modèle entraîne généralement un autre refus. Dirigez la nouvelle tentative vers le modèle de fallback.
• Budgétez les nouvelles tentatives par requête, pas par tour ni par session. Un seul tour peut produire plusieurs refus, par exemple un agent plus ses sous-agents.
• Configurez le fallback sur chaque chemin de requête. Les gestionnaires de nouvelles tentatives, les branches de récupération d'erreur et les workers en arrière-plan en ont tous besoin. Un gestionnaire qui réémet une requête sans fallback perd la protection exactement sur les requêtes les plus susceptibles d'en avoir besoin.
• Donnez aux appels de sous-agents leur propre fallback. Le paramètre fallbacks ne se propage pas aux appels de modèle effectués depuis l'intérieur de l'exécution d'outils.
• Faites du fallback une propriété de la requête, pas d'un état ambiant. Un indicateur partagé, une valeur de configuration mise en cache ou un interrupteur global peut se désynchroniser et laisser silencieusement une requête sans protection. Lorsque vous ne pouvez pas confirmer que le fallback est actif, configurez-le plutôt que de supposer qu'il l'est.
• Instrumentez les refus comme un signal à part entière. Un refus est un HTTP 200, donc une surveillance basée sur les taux d'erreur ou les réponses 5xx ne le voit jamais. Émettez un événement par refus et un par réponse servie par fallback (l'entrée fallback_message dans usage.iterations marque cette dernière), puis alertez sur l'écart entre les deux décomptes.
• Branchez sur stop_reason ou stop_details.type, pas sur content ni sur les champs internes de stop_details. L'objet stop_details est toujours présent lors d'un refus, mais ses champs category et explanation peuvent être null. Vérifiez directement que stop_reason est égal à "refusal".



Prochaines étapes