Dépannage de la réflexion

Cette page couvre les échecs les plus courants lors de la configuration de la réflexion ou de l'aller-retour des blocs de réflexion (le renvoi des blocs de réflexion retournés dans des requêtes ultérieures). La première section associe chaque modèle à ses configurations de réflexion prises en charge et à celles qu'il rejette ; les sections suivantes partent chacune d'un symptôme que vous observez, afin que vous puissiez faire correspondre directement un message d'erreur ou une réponse inattendue à sa cause et à sa correction. Pour comprendre le fonctionnement de la réflexion, consultez la vue d'ensemble Réflexion.

Prise en charge de la réflexion, valeurs par défaut et configurations rejetées par modèle

La plupart des erreurs de configuration de la réflexion proviennent d'une incompatibilité entre la valeur thinking.type de la requête et ce que le modèle prend en charge. Sur la plupart des modèles, la réflexion s'exécute avec thinking: {type: "adaptive"}, et beaucoup l'activent par défaut. Certains modèles plus anciens utilisent plutôt l'« extended thinking » (réflexion étendue), un mode manuel hérité configuré avec thinking: {type: "enabled", budget_tokens: N}.

L'« extended thinking » (réflexion étendue) (thinking.type: "enabled" avec budget_tokens) est dépréciée sur les modèles Claude 4.6 (les requêtes qui l'utilisent aboutissent toujours). Les modèles Claude 4.7 et ultérieurs ne la prennent pas en charge et rejettent les requêtes qui l'utilisent, en renvoyant une erreur 400. Sur les modèles Claude 4.5 et antérieurs qui prennent en charge la réflexion, la réflexion étendue est le seul mode de réflexion disponible. Claude Mythos Preview prend en charge les deux modes. Lorsque les deux modes sont disponibles, utilisez plutôt l'adaptive thinking (réflexion adaptative).

Le tableau indique ce que chaque modèle prend en charge, sa valeur par défaut et les valeurs thinking.type qu'il rejette avec une erreur 400 ; toute valeur non listée comme rejetée est acceptée. Seul Claude Sonnet 5.5 accepte "between_tools", et il prend cette valeur à la place de "disabled".

¹ enabled et budget_tokens fonctionnent toujours sur ces modèles mais sont dépréciés ; utilisez plutôt la réflexion adaptative.
² Claude Opus 5 et Claude Haiku 5.5 acceptent "disabled" avec un effort high ou inférieur ; le combiner avec un effort xhigh ou max renvoie une erreur 400. Sur Claude Opus 5, cette restriction est appliquée à chaque requête. Sur Claude Haiku 5.5, un effort par message différent du niveau en vigueur renvoie également une erreur 400.
³ Claude Sonnet 5.5 accepte "between_tools" avec un effort high ou inférieur. Le combiner avec un effort xhigh ou max renvoie une erreur 400, tout comme un effort par message différent du niveau en vigueur.

Les modèles marqués Always on (Toujours activée) ne peuvent pas désactiver la réflexion. Les modèles marqués On (Activée) réfléchissent par défaut. Claude Opus 5, Claude Sonnet 5 et Claude Haiku 5.5 acceptent thinking: {type: "disabled"}. Sur Claude Sonnet 5.5, envoyez thinking: {type: "between_tools"} pour désactiver la réflexion préalable.

Les modèles Claude 4 plus anciens (Claude Opus 4.1, Claude Sonnet 4 et Claude Opus 4) prennent en charge uniquement la réflexion étendue. Consultez Dépréciations de modèles pour connaître leur disponibilité. Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5 et Claude Mythos 5 ne sont pas disponibles dans le cadre de la conservation zéro des données, sauf autorisation expresse d'Anthropic.

Une erreur 400 indique que "thinking.type.enabled" n'est pas pris en charge

La requête échoue avec une erreur 400 dont le message est le suivant :

"thinking.type.enabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.

Cela se produit parce que le modèle que vous avez demandé a supprimé la réflexion étendue (consultez le tableau de configuration par modèle).

Passez la requête à thinking: {type: "adaptive"} et pilotez la profondeur de réflexion avec effort au lieu de budget_tokens. Migrer vers la réflexion adaptative détaille la conversion.

Une erreur 400 après l'envoi de thinking: {type: "disabled"}

La requête échoue avec une erreur 400. Sur Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Opus 5.5 et Claude Mythos 5, le message est :

"thinking.type.disabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.

Sur Claude Mythos Preview, le seul de ces modèles qui accepte la réflexion étendue, le message est :

"thinking.type.disabled" is not supported for this model. Thinking defaults to adaptive mode when not specified; use "thinking.type.enabled" with "budget_tokens" for extended thinking.

Cela se produit parce que la réflexion est toujours activée pour tous ces modèles (consultez le tableau de configuration par modèle).

Omettez le paramètre thinking ; ces modèles réfléchissent sans aucune configuration. Si votre objectif était d'exclure le texte de réflexion des réponses, utilisez display: "omitted" au lieu de désactiver la réflexion ; consultez Contrôler l'affichage de la réflexion.

Une erreur 400 sur "disabled" peut également se produire sur Claude Opus 5 et Claude Haiku 5.5, qui acceptent thinking: {type: "disabled"} uniquement avec un effort high ou inférieur : le combiner avec un effort xhigh ou max est rejeté. Abaissez le niveau d'effort, ou définissez thinking sur {"type": "adaptive"}.

Sur Claude Sonnet 5.5, thinking: {type: "disabled"} renvoie une erreur 400 à tous les niveaux d'effort. Le message est :

To turn thinking off on this model, send "thinking": {"type": "between_tools"} instead of {"type": "disabled"}. The model does not think before responding. The short updates it writes between tool calls come back as thinking blocks.

Pour désactiver la réflexion préalable sur Claude Sonnet 5.5, envoyez plutôt thinking: {type: "between_tools"}, avec un effort high ou inférieur.

Une erreur 400 indique que "thinking.type.between_tools" n'est pas pris en charge

La requête échoue avec une erreur 400 dont le message est :

"thinking.type.between_tools" is not supported for this model.

Cela se produit parce que seul Claude Sonnet 5.5 accepte thinking: {type: "between_tools"} (consultez le tableau de configuration par modèle).

Envoyez between_tools uniquement à Claude Sonnet 5.5. Sur les autres modèles, omettez thinking ou utilisez une valeur thinking.type que le tableau ne répertorie pas comme rejetée.

Une erreur 400 indique qu'un niveau d'effort n'est pas pris en charge lorsque la réflexion est désactivée

Sur Claude Sonnet 5.5, une requête avec thinking: {type: "between_tools"} et un effort xhigh ou max échoue avec une erreur 400 dont le message est :

output_config.effort 'xhigh' is not supported when thinking is disabled on this model. Use effort 'high' or below, or enable thinking.

Cela se produit parce que Claude Sonnet 5.5 accepte between_tools uniquement avec un effort high ou inférieur. Le message indique que la réflexion est désactivée parce que between_tools n'a pas de réflexion préalable, même si la requête n'a pas envoyé "disabled". Le message nomme le niveau envoyé par la requête.

Abaissez l'effort à high ou inférieur. Pour fonctionner en xhigh ou max, utilisez la réflexion adaptative : omettez le champ thinking ou envoyez thinking: {"type": "adaptive"}. C'est ce que le message entend par « enable thinking ». Claude Sonnet 5.5 rejette "enabled" avec une erreur 400.

Claude Haiku 5.5 renvoie le même message lorsqu'une requête envoie thinking: {type: "disabled"} avec un effort xhigh ou max. Il accepte "disabled" uniquement avec high ou inférieur. Abaissez l'effort, ou définissez thinking sur {"type": "adaptive"}.

Une erreur 400 indique que l'effort ne peut pas changer lorsque la réflexion est désactivée

Sur Claude Sonnet 5.5, une requête avec thinking: {type: "between_tools"} dont l'effort par message change le niveau échoue avec une erreur 400 dont le message est :

messages.N: output_config.effort 'low' differs from the 'high' in effect before it; effort cannot change when thinking is disabled on this model. Use effort 'high', or enable thinking.

Le message indique que la réflexion est désactivée parce que between_tools n'a pas de réflexion préalable. Avec between_tools, l'effort ne peut pas changer en cours de conversation : un output_config.effort par message différent du niveau en vigueur renvoie une erreur 400. messages.N est la position du message qui a défini le nouveau niveau.

Supprimez cet effort par message, ou définissez-le sur le niveau en vigueur. Pour faire varier l'effort à chaque tour, utilisez la réflexion adaptative : omettez le champ thinking ou envoyez thinking: {"type": "adaptive"}. C'est ce que le message entend par « enable thinking ».

Claude Haiku 5.5 renvoie le même message lorsqu'une requête avec thinking: {type: "disabled"} définit un effort par message différent du niveau en vigueur. Supprimez cet effort par message, ou définissez thinking sur {"type": "adaptive"} pour faire varier l'effort à chaque tour.

Une erreur 400 indique que la réflexion adaptative n'est pas prise en charge

La requête échoue avec une erreur 400 dont le message est le suivant :

adaptive thinking is not supported on this model

Cela se produit parce que le modèle ne prend en charge que la réflexion étendue (consultez le tableau de configuration par modèle).

Utilisez plutôt thinking: {type: "enabled", budget_tokens: N} ; consultez Réflexion étendue pour la configuration.

Une erreur 400 indique que les blocs de réflexion ne peuvent pas être modifiés

Une requête qui renvoie des résultats d'outils échoue avec une erreur 400 invalid_request_error dont le message contient :

`thinking` or `redacted_thinking` blocks in the latest assistant message cannot be modified

Dans les conversations multi-tours et avec « tool use » (utilisation d'outils), vous renvoyez à l'API les messages précédents de l'assistant, y compris leurs blocs thinking et redacted_thinking, et l'API vérifie qu'ils arrivent sans modification. Cette erreur se produit lorsque le message de l'assistant que vous renvoyez diffère de celui que l'API a retourné, le plus souvent parce que votre code filtre les blocs de contenu par type et supprime les blocs redacted_thinking, ou reconstruit le message de l'assistant au lieu de le renvoyer tel quel.

Renvoyez le tour de l'assistant mot pour mot, blocs de réflexion inclus. Consultez Préserver les blocs de réflexion pour les règles, et l'aller-retour détaillé dans La réflexion dans les flux de travail avec outils et multi-tours pour un code correct dans chaque SDK.

Une erreur 400 indique qu'une signature de bloc de réflexion est invalide

Une requête adressée à Claude Fable 5.1, Claude Opus 5.5, Claude Sonnet 5.5 ou Claude Haiku 5.5 qui rejoue des blocs de réflexion antérieurs échoue avec une erreur 400 invalid_request_error dont le message est :

messages.{i}.content.{j}: Invalid `signature` in `thinking` block. The block is bound to a different conversation. Remove the block, or set `thinking.block_binding.prefix_mismatch_behavior` to "drop_block".

Si la requête n'a pas envoyé l'en-tête bêta thinking-binding-controls-2026-08-01, le message ajoute That setting requires the `thinking-binding-controls-2026-08-01` value in the `anthropic-beta` header.

Le message se termine généralement par une phrase indiquant ce qui a changé : le prompt system, la liste tools, le premier message ou bloc qui diffère, un contenu manquant ou nouveau, ou un bloc de réflexion antérieur manquant ou dans le désordre. Cette phrase est destinée aux personnes et aux journaux. Sa formulation peut changer, ne vous y fiez donc pas dans votre code.

Si le message s'arrête après Invalid `signature` in `thinking` block, c'est la signature elle-même qui n'a pas été vérifiée : elle a été tronquée, modifiée ou renvoyée vide, et prefix_mismatch_behavior ne s'applique pas. Un texte de réflexion modifié renvoie une erreur différente. Consultez Une erreur 400 indique que les blocs de réflexion ne peuvent pas être modifiés.

Sur Claude Fable 5.1, Claude Opus 5.5, Claude Sonnet 5.5 et Claude Haiku 5.5, l'API n'accepte un bloc de réflexion rejoué que tant que l'invite système system, les tools et les messages qui le précèdent restent inchangés. Consultez Conserver le préfixe inchangé. L'erreur signifie que quelque chose de plus ancien dans la conversation a changé entre les requêtes : un tour modifié, réordonné ou supprimé, un rappel par tour injecté puis supprimé, une invite système system ou un tableau tools reconstruit, ou une compaction côté client qui a conservé mot pour mot les tours récents et leur réflexion. La vérification est appliquée pour les nouveaux comptes créés à partir du 31 août 2026, et pour toute requête qui définit thinking.block_binding.prefix_mismatch_behavior. La compaction et l'édition du contexte côté serveur ne la déclenchent jamais.

Pour corriger cela, conservez un historique en ajout seul : renvoyez les tours précédents exactement tels qu'ils ont été envoyés et reçus, ajoutez des instructions avec un message système en cours de conversation au lieu de modifier system ou tools, et laissez l'édition du contexte ou la compaction côté serveur effectuer tout élagage. Réessayer avec le même corps de requête n'élimine pas l'erreur. Pour poursuivre cette requête sans le raisonnement invalidé, envoyez l'en-tête bêta thinking-binding-controls-2026-08-01 et définissez thinking.block_binding.prefix_mismatch_behavior sur "drop_block". Vous pouvez aussi supprimer tous les blocs thinking et redacted_thinking de l'historique (au minimum le bloc nommé et tous ceux qui le suivent, dans ce tour et tous les tours ultérieurs), laisser en place les autres blocs de chaque tour, et réessayer une fois. Sur Claude Sonnet 5.5 et Claude Haiku 5.5, block_binding fonctionne uniquement avec thinking: {"type": "adaptive"}. Avec between_tools sur Claude Sonnet 5.5, ou thinking: {"type": "disabled"} sur Claude Haiku 5.5, conservez un historique en ajout seul, ou supprimez les blocs de réflexion à partir du tour modifié.

Un bloc provenant d'un modèle que le modèle cible ne peut pas lire ne produit jamais cette erreur : l'API le supprime et, avec l'en-tête bêta, le signale dans input_transformations.

Le champ thinking est vide dans la réponse

La réponse contient des blocs thinking, mais leur champ thinking est une chaîne vide et seul le champ signature est renseigné.

Cela se produit parce que display vaut par défaut "omitted" sur les modèles récents, ce qui renvoie les blocs de réflexion sans leur texte.

Définissez display: "summarized" dans votre configuration de réflexion pour recevoir le texte de réflexion résumé. Consultez Contrôler l'affichage de la réflexion pour les valeurs par défaut par modèle. Si vous ne souhaitez que les courtes lignes d'état que certains modèles écrivent entre les appels d'outils, et non le raisonnement, définissez plutôt display: "updates" (bêta). Consultez Mises à jour de progression entre les appels d'outils.

Un bloc dont le champ thinking est vide reste complet : la signature contient le raisonnement. Renvoyez-le avec le tour comme n'importe quel autre bloc. Consultez Renvoyer les tours de l'assistant exactement tels qu'ils ont été retournés.

Aucun bloc de réflexion n'apparaît sur certains tours

Certaines réponses ne contiennent aucun bloc thinking, même si la réflexion est configurée.

C'est normal en mode adaptatif : Claude ignore la réflexion pour les requêtes qu'il juge suffisamment simples pour y répondre directement.

Si vous souhaitez une réflexion plus fréquente ou plus approfondie, augmentez effort ou orientez-la par le prompt ; consultez Piloter la fréquence de réflexion de Claude.

Un tool_choice forcé ({"type": "any"} ou un outil nommé) ne renvoie pas non plus de bloc thinking : la réponse commence par l'appel d'outil. Pour permettre au modèle de réfléchir avant d'appeler un outil, utilisez tool_choice: {"type": "auto"} et indiquez dans le prompt quand utiliser l'outil.

Des appels d'outils ou des balises XML apparaissent dans la sortie texte

Une réponse écrit parfois un appel d'outil dans son texte au lieu d'émettre un bloc tool_use, ou inclut <thinking> ou d'autres balises XML internes dans son texte visible. Un appel d'outil ayant fuité ne s'exécute jamais, et dans les boucles agentiques le texte ayant fuité reste dans l'historique de la conversation, de sorte que les tours ultérieurs sont également affectés.

Cela se produit sur Claude Opus 5 lorsque la réflexion est désactivée, le plus souvent sur des charges de travail à forte utilisation d'outils comme la recherche. Les règles de l'invite système demandant au modèle de ne pas réfléchir ou de ne pas raisonner augmentent la fuite de balises.

Réactivez la réflexion (la valeur par défaut) et utilisez plutôt des niveaux d'effort plus faibles pour contrôler le coût en tokens. Si votre intégration doit garder la réflexion désactivée, appliquez les mesures d'atténuation par le prompt décrites dans Fonctionner avec la réflexion désactivée.

La réponse s'arrête avec stop_reason: "max_tokens"

La réponse se termine avec stop_reason: "max_tokens", souvent avec un bloc de texte tronqué ou manquant.

Cela se produit parce que les tokens de réflexion sont comptabilisés dans max_tokens, de sorte qu'une longue passe de réflexion peut consommer le budget avant que la réponse texte ne soit terminée.

Augmentez max_tokens pour laisser de la place à la fois à la réflexion et au texte, ou réduisez effort pour que Claude dépense moins en réflexion ; consultez Contrôle des coûts et La réflexion et la fenêtre de contexte.

Les succès de cache chutent après modification des paramètres de réflexion

cache_read_input_tokens tombe à zéro sur des requêtes qui atteignaient auparavant le cache.

Cela se produit parce que la configuration de réflexion et le niveau d'effort (ou sa valeur par défaut) font partie du préfixe de prompt mis en cache, de sorte que modifier l'un d'eux démarre un nouveau préfixe : changer de mode de réflexion, modifier la valeur d'effort et modifier budget_tokens invalident tous les points de rupture du cache des messages, et peuvent également invalider les points de rupture des outils et de l'invite système, selon l'endroit où le modèle restitue la configuration.

Gardez la configuration de réflexion et le niveau d'effort constants entre les requêtes qui partagent une conversation ; définir explicitement un paramètre à sa valeur par défaut équivaut à l'omettre et n'invalide rien. Consultez La réflexion et la mise en cache des prompts.

Définir l'effort ne modifie pas la réflexion

Vous modifiez effort mais la fréquence ou la profondeur de réflexion reste la même.

Cela se produit parce que l'effort n'est le principal levier de réflexion qu'en mode adaptatif. Sur les modèles à réflexion étendue uniquement, la profondeur de réflexion est définie par budget_tokens.

Ajustez budget_tokens sur ces modèles, ou vérifiez dans quel mode votre modèle s'exécute ; consultez Réflexion et effort. Sur Claude Opus 4.5, le seul modèle à réflexion étendue uniquement qui prend en charge l'effort, l'effort se combine avec le budget ; consultez Règles et réglage du budget.

Étapes suivantes