Refus et repli

Claude Fable 5.1, 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". Son champ stop_details.category nomme le domaine de politique concerné (voir À quoi ressemble un refus). Vous pouvez généralement encore 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 l'un de ces modèles et souhaitez que les requêtes déclinées basculent automatiquement vers un autre modèle. Elle s'applique également lorsque vous avez vu "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 éviter de payer deux fois le coût de la mise en cache des prompts lorsque vous construisez vous-même la 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, en bêta sur l'API Claude : définissez fallbacks sur "default", et l'API relance une requête déclinée sur le modèle de repli (« fallback ») qu'Anthropic recommande pour sa catégorie de refus. Pour les catégories sans repli 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 décrivent ce que contient 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.
• recommended_model : présent uniquement sur les requêtes qui définissent fallbacks (repli côté serveur, bêta). Il nomme un modèle sur lequel relancer directement lorsque l'API a ignoré la tentative de repli (par exemple, le modèle de repli était soumis à une limite de débit), et vaut null sinon. C'est une indication, pas une garantie.
• category et explanation valent tous deux 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 vaut 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 écartez-la.

Choisir une approche de repli

Il existe trois façons de relancer une requête refusée sur un autre modèle. La bonne dépend de l'endroit où vous exécutez votre code 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 relance 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 dispose d'un repli 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 repli de votre choix. Dans les deux cas, 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

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 repli 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 au fil de l'évolution des recommandations.

Le routage par défaut ne déclenche jamais le rejet préalable pour image surdimensionnée pour des modèles que vous n'avez pas choisis : un modèle routé qui redimensionnerait une image marquée "oversized_image": "error" est plutôt retiré du routage, de sorte qu'une image marquée n'est jamais servie redimensionnée.

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 fourni 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 se replier sur un modèle moins performant ou être déclinée. Le mode "default" encode pour vous ces recommandations par modèle et par catégorie, de sorte qu'une requête refusée est relancée sur le modèle qu'Anthropic recommande pour cette catégorie. Les replis 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 passage de relais.

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 repli. 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 repli

Au lieu du routage par défaut, vous pouvez définir fallbacks sur une liste de trois modèles au maximum. 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 souhaitez contrôler exactement quels modèles servent les requêtes refusées, par exemple pour épingler un modèle que votre application a qualifié.

Les modèles de repli nommés comptent pour la vérification d'image surdimensionnée : une requête dont le bloc image définit "oversized_image": "error" est vérifiée au préalable par rapport au modèle demandé et à chaque repli nommé, est rejetée si l'un d'eux redimensionnerait cette image, et la cible de redimensionnement indiquée dans le rejet convient à tous.

Les lignes surlignées sont la seule différence avec la requête à routage par défaut.

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 repli ne prend pas en charge une fonctionnalité utilisée par la requête, l'API rejette la requête d'emblée.
• Comme avec le mode par défaut, 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.
• Si un modèle de repli est soumis à une limite de débit ou surchargé, la tentative de repli n'est pas effectuée et le refus précédent est renvoyé à la place. Le champ stop_details.recommended_model du refus nomme alors un modèle sur lequel relancer directement. Dimensionnez les limites de débit du modèle de repli pour le volume de refus que vous prévoyez, sinon les replis se dégradent en refus sous charge.

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 passage de relais, 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 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 décline est le modèle demandé.
  • to.model est toujours l'identifiant résolu du modèle qui poursuit.

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 tous les modèles de la chaîne déclinent, 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.

Le routage persistant peut envoyer un tour ultérieur directement au modèle de repli. Un tel tour ne porte aucun bloc de contenu fallback, car aucun modèle n'a décliné ce tour. Identifiez-le par l'entrée fallback_message dans usage.iterations, l'absence d'entrée message pour le modèle demandé, et le champ model de la réponse.

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 décliné a produits avant le passage de relais. 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 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 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 repli poursuit à 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 dans le champ to.model du bloc fallback et dans l'entrée fallback_message du usage.iterations du dernier message_delta.

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 ayant décliné, 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 déclinée et ses jetons de sortie apparaissent toujours dans usage.iterations.

Facturation et limites de débit

Une tentative qui a décliné avant de produire la moindre sortie n'est pas facturée : ses jetons sont indiqués dans son entrée usage.iterations mais ne sont pas facturés. Chaque tentative ayant produit une sortie, y compris une tentative qui a décliné en cours de réponse, est facturée séparément aux tarifs du modèle qui l'a exécutée. Le tableau usage.iterations est le relevé par tentative de ce qui vous est facturé. Les décomptes usage de premier niveau décrivent uniquement la tentative qui a produit le message renvoyé. Les jetons de modèles différents ne sont jamais additionnés dans un même champ.

Chaque tentative exécutée, y compris une tentative qui a décliné, compte dans les limites de débit de son propre modèle.

Routage persistant

Après qu'une conversation s'est repliée, l'API enregistre quel modèle l'a servie. Les requêtes ultérieures pour cette conversation qui incluent fallbacks vont directement à ce modèle de repli, sans exécuter le modèle demandé. Cela évite de payer à chaque tour une tentative qui serait de manière prévisible déclinée à nouveau.

Quelques propriétés de la décision de routage :

• Elle est conservée pendant environ 1 heure et est limitée à votre organisation.
• Elle est stockée sous forme de hachage de contenu du préfixe de conversation plus le modèle qui l'a servie. Le contenu des messages lui-même n'est pas stocké.
• Elle est fournie au mieux, votre code doit donc gérer le fait que le modèle demandé soit réessayé à tout moment.

Le routage persistant s'applique aux requêtes avec et sans streaming. Sur une requête en streaming, la décision de routage est prise avant l'ouverture du flux, de sorte que le champ model de l'événement message_start porte déjà l'identifiant du modèle de repli.

Repli côté client avec le middleware SDK

Chaque SDK Anthropic inclut 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 relancent 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 de 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 à 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
# raccorde ses événements au 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}")

# 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.
• Lorsque tous les modèles de la liste ont 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.1 ou 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. Le modèle de repli ne peut pas lire les blocs Claude Fable 5.1, qui sont préservés uniquement pour ce modèle ou un plus récent, l'API les supprime donc.
• Les réponses servies via le middleware incluent un bloc de contenu fallback à chaque frontière 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 solliciter à nouveau un modèle qui a refusé.

Écrire vous-même la nouvelle tentative

En HTTP brut ou avec une logique de nouvelle tentative personnalisée, implémentez le modèle que le middleware encapsule :

1. 1

   Détecter le refus

   Vérifiez la présence de stop_reason: "refusal" dans la réponse.

2. 2

   Renvoyer sur un modèle de repli

   Envoyez la même requête avec model défini sur un modèle de repli, tel que Claude Opus 4.8. Un autre modèle peut normalement servir une requête que Claude Fable 5.1 ou Claude Fable 5 décline. La façon dont vous gérez l'historique de conversation dépend de l'utilisation ou non d'un crédit de repli :

   • Sans utilisation de crédit : vous pouvez laisser en place les blocs thinking et redacted_thinking antérieurs ou les retirer pour économiser des jetons d'entrée. Le modèle de repli ne peut pas les utiliser dans les deux cas : il ignore les blocs Claude Fable 5, et les blocs Claude Fable 5.1 sont préservés uniquement pour ce modèle ou un plus récent, l'API les supprime donc.
   • Avec utilisation de crédit : envoyez le corps sans modification, car l'utilisation du crédit exige une correspondance exacte. Le serveur gère les blocs de réflexion du modèle précédent lors d'une utilisation de crédit, ne les retirez donc pas (voir Champs qui doivent correspondre à la requête refusée).
3. 3

   Rester sur le modèle de repli

   Pour les conversations à plusieurs tours, continuez à utiliser le modèle de repli pour les tours suivants plutôt que de revenir en arrière.

Une nouvelle tentative manuelle écrit le cache de prompts du modèle de repli à partir de zéro, ce qui coûte plus cher que la lecture d'un cache existant. Le crédit de repli rembourse ce coût ; utilisez-le sur chaque nouvelle tentative que vous construisez vous-même.

Refus dans les Message Batches

Une requête refusée dans un Message Batch revient avec result.type: "succeeded" et 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 ne génèrent pas de crédits de repli, de sorte que stop_details sur un résultat de lot n'inclut jamais de fallback_credit_token.

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 relancer les éléments de lot refusés :

1. Collectez les éléments refusés dans les résultats.
2. Retirez les blocs de réflexion Claude Fable 5.1 ou Claude Fable 5 de tout historique à plusieurs 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

• Relancez 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étez les nouvelles tentatives par requête, et non 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 nouvelle tentative, 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 aux 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, et non d'un état ambiant. Un indicateur partagé, une valeur de configuration en cache ou une bascule globale peut se désynchroniser et laisser silencieusement une requête sans protection. 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 un signal à part entière. Un refus est un HTTP 200, de sorte qu'une surveillance fondé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 décomptes.
• Branchez sur stop_reason ou stop_details.type, et non sur content ou les champs internes de stop_details. L'objet stop_details est toujours présent sur un refus, mais ses champs category et explanation peuvent valoir null. Vérifiez directement que stop_reason est égal à "refusal".

Étapes suivantes