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 (renvoyer les blocs de réflexion retournés dans des requêtes ultérieures). La première section associe chaque modèle aux configurations de réflexion qu'il prend 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 un message d'erreur ou une réponse inattendue directement à sa cause et à sa correction. Pour comprendre le fonctionnement de la réflexion, consultez la vue d'ensemble Réflexion.



Configurations que chaque modèle rejette

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 les modèles actuels, la réflexion s'exécute avec thinking: {type: "adaptive"}, et sur les plus récents, elle est activée par défaut. Certains modèles antérieurs utilisent à la place la réflexion étendue, un mode manuel hérité configuré avec thinking: {type: "enabled", budget_tokens: N}.

La « 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 la réflexion adaptative.

Le tableau indique ce que chaque modèle prend en charge, sa valeur par défaut et les valeurs de 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 obsolètes ; utilisez plutôt la réflexion adaptative.
² Claude Opus 5 accepte "disabled" avec un 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 ont la réflexion par défaut mais acceptent thinking: {type: "disabled"}.

Les modèles Claude 4 antérieurs (Claude Sonnet 4 et Claude Opus 4) prennent en charge uniquement la réflexion étendue ; consultez les dépréciations de modèles pour leur disponibilité. Claude Fable 5 et Claude Mythos 5 ne sont pas disponibles sous rétention zéro des données.



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 indique :

"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 (voir Configurations que chaque modèle rejette).

Basculez la requête vers 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 indique :

"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, Claude Mythos 5 et Claude Mythos Preview rejettent "disabled". Sur Claude Fable 5 et Claude Mythos 5, la suggestion de "thinking.type.enabled" dans le texte de l'erreur ne s'applique pas non plus : ces modèles la rejettent également.

Omettez le paramètre thinking ; ces modèles réfléchissent sans aucune configuration. Si votre objectif était de garder le texte de réflexion hors 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 accepte 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 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 indique :

adaptive thinking is not supported on this model

Cela se produit parce que le modèle prend en charge uniquement la réflexion étendue (voir Configurations que chaque modèle rejette).

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 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 du code correct dans chaque SDK.



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 a pour valeur par défaut "omitted" sur les modèles plus 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 de chaque modèle.



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 saute la réflexion sur les requêtes qu'il juge suffisamment simples pour y répondre directement.

Si vous souhaitez que la réflexion soit plus fréquente ou plus approfondie, augmentez effort ou orientez-la via le prompt ; consultez Orienter 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 occasionnellement 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 qui a fui ne s'exécute jamais, et dans les boucles agentiques, le texte qui a fui 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 intensives en outils comme la recherche. Les règles d'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 des niveaux d'effort plus bas pour contrôler le coût en tokens à la place. Si votre intégration doit garder la réflexion désactivée, appliquez les mesures d'atténuation par prompt décrites dans Exécution 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 comptent dans max_tokens, donc une longue passe de réflexion peut consommer le budget avant que la réponse textuelle ne soit terminée.

Augmentez max_tokens pour laisser de la place à la fois à la réflexion et au texte, ou abaissez 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 hits de cache chutent après avoir modifié les 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 la réflexion et le niveau d'effort (ou sa valeur par défaut) font partie du préfixe de prompt mis en cache, donc 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 de 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 rend 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 pas. Consultez Réflexion et mise en cache des prompts.



Définir l'effort ne change 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 est le levier principal de la réflexion uniquement en mode adaptatif. Sur les modèles à réflexion étendue uniquement, la profondeur de réflexion est définie par budget_tokens à la place.

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 compose avec le budget ; consultez Règles de budget et réglage.



Prochaines étapes