Refus et repli

Claude Fable 5 inclut des classificateurs de sécurité qui peuvent refuser 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 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.

Consultez cette page lorsque vous développez avec Claude Fable 5 et souhaitez que les requêtes refusées soient automatiquement transmises à un autre modèle. Elle s'applique également lorsque vous venez de voir "refusal" dans une réponse et souhaitez savoir quoi faire ensuite.

Pages connexes :

• Raisons d'arrêt et repli : la liste complète des valeurs de stop_reason.
• Crédit de repli : 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 SDK : l'utilitaire SDK qui encapsule tout cela.
• Cookbook sur le repli et la facturation : un exemple complet de bout en bout.

La configuration la plus simple : nommez un modèle de repli dans la requête, et l'API gère la nouvelle tentative.

client = Anthropic()

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

Les sections ci-dessous couvrent le contenu d'une réponse de refus, quand utiliser le repli 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 pas à une 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 arriver avant toute sortie, ou en cours de streaming après une sortie partielle. Dans les deux cas, considérez toute sortie partielle comme incomplète et supprimez-la.



Choisir une approche de repli

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

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



Repli côté serveur

Le repli côté serveur réessaie une requête refusée au sein d'un seul appel API. Vous nommez jusqu'à trois modèles de repli, et lorsque Claude Fable 5 refuse, l'API exécute le modèle suivant de la chaîne sur la même requête. Vous recevez une seule réponse qui nomme le modèle ayant répondu, de sorte que votre utilisateur obtient une réponse en un seul aller-retour.



Effectuer la requête

Nommez les modèles de repli dans le paramètre fallbacks et envoyez l'en-tête bêta server-side-fallback-2026-06-01.

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

# Une entrée fallback_message dans usage.iterations indique qu'un modèle de repli a été exécuté ;
# associez-la à stop_reason pour confirmer que le modèle de 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,
        }
    )
)

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 de l'API Models.
• Chaque entrée nomme un model et peut remplacer max_tokens et thinking 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 repli ne prend pas en charge une fonctionnalité utilisée par la requête, l'API rejette la requête d'emblée.
• Seul un refus du classificateur de sécurité déclenche le repli. Une limite de débit, une surcharge ou une erreur serveur sur le modèle demandé vous est renvoyée telle quelle.



Contenu de la réponse

La réponse ressemble à tout autre message, avec deux ajouts :

• Le champ model de niveau supérieur indique le modèle qui a produit le message renvoyé, qu'il s'agisse du modèle demandé ou d'un modèle de repli.
• Un bloc de contenu fallback marque chaque point dans 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 l'étape qui refuse 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 :

{
  "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 refusé 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 tous les modèles de la chaîne refusent, la réponse est le refus du dernier modèle, avec une entrée message pour chaque étape précédente et une entrée fallback_message pour la dernière.



Poursuivre la conversation

Au tour suivant, renvoyez le contenu de l'assistant tel que vous l'avez reçu. Après un repli en cours de sortie, content peut inclure des types de blocs que le modèle ayant refusé a produits avant le transfert ; le tableau ci-dessous 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 repli, et le bloc fallback est le premier bloc de contenu.
• Comme message_start attend que la tentative de repli démarre, le délai avant le premier octet inclut la tentative refusé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 limite.
• Le modèle de repli continue à partir de la sortie partielle. Seuls les blocs text de la sortie partielle sont transmis au modèle de repli 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 servant à partir du to.model du bloc fallback et de l'entrée fallback_message dans le 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 refusé, et le modèle de repli répond à partir de zéro. Le résultat ressemble à un refus avant toute sortie, avec le bloc fallback en premier. La tentative refusée et ses tokens de sortie apparaissent toujours dans usage.iterations.



Repli côté client avec le middleware SDK

Les SDK TypeScript, Python, Go, Java et C# incluent un middleware de repli sur refus. Vous le configurez une fois sur le client avec votre liste de modèles de repli. 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-06-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 instance BetaFallbackState entre les requêtes d'une conversation.

# En cas de refus, le middleware réessaie avec le modèle de repli indiqué et
# envoie automatiquement l'en-tête bêta de crédit de repli sur chaque requête traitée.
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 avec 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 event in stream:
        if event.type == "text":
            print(event.text, end="", flush=True)
    final_message = stream.get_final_message()
print(f"\nserved by: {final_message.model}")

# Sans 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}")



Comportement

• Les nouvelles tentatives parcourent votre liste de repli dans l'ordre. Un modèle de repli qui refuse lui-même transmet la requête à l'entrée suivante.
• La réponse de refus originale n'est renvoyée que lorsque tous les modèles de la liste ont refusé. Le middleware ne lève pas d'erreur pour cela.
• Les blocs de réflexion de Claude Fable 5 sont gérés pour vous : le middleware les supprime de la nouvelle tentative et les gère dans l'historique de conversation lors des requêtes ultérieures.
• Les réponses servies via le middleware incluent un bloc de contenu fallback à chaque limite de modèle, comme les réponses de repli 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 avec result.type: "succeeded" et stop_reason: "refusal". Le champ stop_details peut être null sur les résultats de lot, détectez donc les refus en vérifiant directement stop_reason.

Le repli 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. Supprimez les blocs de réflexion de Claude Fable 5 de tous les historiques multi-tours.
3. Soumettez-les à nouveau sur un modèle de repli 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 repli.
• Budgétisez les nouvelles tentatives par requête, pas par tour ou par session. Un seul tour peut produire plusieurs refus, par exemple un agent plus ses sous-agents.
• Configurez le repli 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 repli perd la protection précisément sur les requêtes les plus susceptibles d'en avoir besoin.
• Donnez aux appels de sous-agents leur propre repli. Le paramètre fallbacks ne se propage pas dans les appels de modèle effectués depuis l'intérieur de l'exécution d'outils.
• Faites du repli une propriété de la requête, pas d'un état ambiant. Un indicateur partagé, une valeur de configuration mise en cache ou un commutateur global peut se désynchroniser et laisser silencieusement une requête non protégée. Lorsque vous ne pouvez pas confirmer que le repli est actif, configurez-le plutôt que de supposer qu'il est activé.
• Instrumentez les refus comme leur propre signal. 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 repli (l'entrée fallback_message dans usage.iterations marque cette dernière), puis alertez sur l'écart entre les deux comptages.
• Branchez sur stop_reason, pas sur stop_details ou content. stop_details est informatif et peut être null sur un refus. Vérifiez directement que stop_reason est égal à "refusal".



Étapes suivantes