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 sous la forme thinking: {type: "adaptive"}, et beaucoup l'activent par défaut. Certains modèles plus anciens utilisent à la place l'« extended thinking » (réflexion étendue), un mode manuel hérité configuré sous la forme 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 répertoriée comme rejetée est acceptée.

¹ 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 accepte "disabled" à un niveau d'effort high ou inférieur ; le combiner avec un effort xhigh ou max renvoie une erreur 400. Cette restriction s'applique à Claude Opus 5 et aux modèles ultérieurs et est appliquée à chaque requête.

Les modèles marqués Toujours activée ne peuvent pas désactiver la réflexion. Les modèles marqués Activée réfléchissent par défaut mais acceptent thinking: {type: "disabled"}.

Les modèles Claude 4 antérieurs (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 rétention 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 indique que "thinking.type.disabled" n'est pas pris en charge

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

"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 sur les modèles où la réflexion est toujours activée : Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5 et Claude Mythos Preview rejettent "disabled". Tous ces modèles, à l'exception de Claude Mythos Preview, rejettent également le "thinking.type.enabled" suggéré par le texte de l'erreur.

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, qui n'accepte thinking: {type: "disabled"} qu'à un niveau d'effort high ou inférieur : le combiner avec un effort xhigh ou max est rejeté. Réduisez le niveau d'effort ou laissez la réflexion activée.

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 que la signature d'un bloc de réflexion est invalide

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

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 peut également se terminer par une phrase désignant le premier message qui a changé. Si le message ne comporte aucune clause de motif, le contenu du bloc a été modifié. Consultez Une erreur 400 indique que les blocs de réflexion ne peuvent pas être modifiés.

Sur Claude Fable 5.1, l'API accepte un bloc de réflexion rejoué uniquement tant que le prompt system, les tools et les messages qui le précédaient sont inchangés. L'erreur signifie que quelque chose plus tôt dans la conversation a changé entre les requêtes : un tour modifié, réordonné ou supprimé, un rappel par tour qui a été injecté puis supprimé, un prompt 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 côté serveur et l'édition de contexte ne la déclenchent jamais.

Pour corriger cela, gardez l'historique en ajout seul : renvoyez les tours antérieurs 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 de contexte ou la compaction côté serveur effectuer tout élagage. Réessayer avec le même corps de requête n'efface 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 également retirer chaque bloc thinking et redacted_thinking de l'historique (au minimum le bloc désigné 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.

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.

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.

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