Vérifications du préfixe sur les blocs de réflexion

Chaque requête qui renvoie des « thinking blocks » (blocs de réflexion) à un modèle avec « preserved thinking » (réflexion préservée) fait l’objet d’un « prefix check » (vérification du préfixe). Une vérification du préfixe échoue si system, tools ou un message antérieur a été modifié après que Claude a produit un bloc. Elle échoue également si un bloc de réflexion situé entre d’autres a été omis ou déplacé.

L’échec de la vérification du préfixe peut entraîner ou non une erreur 400, selon le modèle : gérez donc les deux cas.

Qui est concerné par la vérification du préfixe

Vous n’avez rien à modifier si l’une de ces conditions est remplie :

• Claude Code, claude.ai ou Claude Managed Agents gère l’historique de votre conversation.
• Le Claude Agent SDK gère l’historique, et l’invite système que vous fournissez au SDK reste identique.
• Votre code suit les trois habitudes d’une intégration en ajout seul, et rien ne réécrit ses requêtes en chemin.
• Vous n’appelez aucun modèle avec réflexion préservée.

Si vos requêtes transitent par une bibliothèque, un proxy ou une passerelle, comparez ce qu’il envoie avec ce que vous avez envoyé. Si vous en exploitez un, consultez Bibliothèques, proxys et passerelles pour savoir ce qu’il faut transmettre.

Ce qui doit rester identique, et pourquoi

Faites de votre intégration une intégration en ajout seul. Trois habitudes y parviennent :

1. Renvoyez chaque tour de l’assistant exactement tel que l’API l’a renvoyé, y compris les blocs de réflexion dont le texte est vide.
2. Construisez system et tools une seule fois pour chaque conversation, et envoyez cette copie à chaque fois.
3. Placez chaque mise à jour dans un nouveau message à la fin, et laissez-la là.

Le raisonnement de chaque bloc de réflexion porte exactement sur ce qui le précède : system, tools et chaque message antérieur. Ce contenu est le préfixe du bloc, et c’est ce que compare la vérification du préfixe.

La vérification du préfixe est similaire à la mise en cache des prompts, sauf qu’une modification rend invalide la réflexion qui la suit au lieu de simplement manquer le cache.

Prenons une application qui place la date du jour dans son invite système. À minuit, la date change, tout comme le préfixe de la réflexion déjà présente dans la conversation. Cette réflexion devient invalide, et la requête suivante peut échouer. Une application en ajout seul conserve l’invite système telle qu’elle était, et indique la nouvelle date dans un message à la fin.

Une modification rend invalide uniquement la réflexion qui la suit déjà. La réflexion qui la précède et la réflexion que Claude produit ensuite restent valides.

Si votre code modifie l’invite système, les outils ou l’historique

D’autres causes, comme le fait d’ignorer les blocs de réflexion dont le texte est vide ou de reconstruire une conversation enregistrée, ont leurs propres correctifs : consultez Modifier les outils ou les instructions sans échouer à la vérification du préfixe. Pour trouver la vôtre, demandez à un agent d’examiner votre code.

Ce que fait chaque modèle lorsque la vérification du préfixe échoue

Sur la Claude API et certaines plateformes cloud, le résultat d’un échec de la vérification du préfixe lorsque prefix_mismatch_behavior est omis dépend du modèle :

Lorsque le tableau indique « Erreur 400 possible », il existe deux cas : une requête qui échoue à la vérification du préfixe peut obtenir une erreur 400 ou aucune erreur. Lorsqu’aucune erreur n’est renvoyée, les blocs qui échouent à la vérification du préfixe parviennent au modèle. Claude les lit comme n’importe quelle autre entrée, ils vous sont facturés, et Claude travaille à partir d’un raisonnement portant sur un contenu qui a changé depuis.

Sur ces modèles, vous pouvez déterminer quel cas une requête obtient, mais gérez les deux cas.

Les éléments de Message Batches qui omettent prefix_mismatch_behavior n’obtiennent aucune erreur, et l’API peut écarter les blocs qui échouent à la vérification du préfixe.

Gérer les deux cas

Pour obtenir un seul résultat sur chaque requête, faites de votre intégration une intégration en ajout seul ou définissez prefix_mismatch_behavior. Sinon, votre code doit gérer les deux comportements.

• En ajout seul : avec les trois habitudes, votre code ne fait pas échouer une requête à la vérification du préfixe.
• Le réglage : avec "error" sur chaque requête, chaque échec est une erreur 400, et vous l’interceptez dans le code.
• Les deux comportements : si vous omettez le réglage, interceptez l’erreur 400, et surveillez la réflexion ayant échoué à la vérification du préfixe qui a atteint Claude.

Après une erreur 400, envoyez "drop_block" sur les requêtes ultérieures de cette conversation pour la rétablir. Cela a un coût : consultez Ce que coûte le fait d’écarter la réflexion. Ne l’envoyez pas sur toutes vos conversations pour masquer les erreurs.

Détails techniques

Fonctionnement de la vérification du préfixe

Les modèles avec réflexion préservée enregistrent une empreinte du préfixe de chaque bloc de réflexion dans sa signature. La référence de l’API appelle la vérification du préfixe la vérification de la conversation, et l’erreur 400 indique qu’un bloc ayant échoué à la vérification du préfixe is bound to a different conversation.

Quels modèles exécutent la vérification du préfixe

La vérification du préfixe s’exécute sur la Claude API et sur certaines plateformes cloud. Elle vérifie les blocs de réflexion qu’un modèle avec réflexion préservée a produits, sur les requêtes adressées à l’un de ces modèles. Sur la Claude API, les autres modèles, comme Claude Opus 5, ne l’exécutent pas, et elle ne couvre pas leurs blocs.

Ce qui compte comme une modification

• Chaque bloc est comparé à son propre enregistrement. L’API compare ce qui précède un bloc dans cette requête avec ce que sa signature a enregistré lorsque Claude l’a produit. Votre dernière requête ne joue aucun rôle. La vérification du préfixe ne porte que sur le contenu, et non sur les sessions, les identifiants ou les utilisateurs. Le même contenu dans une nouvelle requête ou une bifurcation la passe.
• La vérification du préfixe compare ce que vous avez envoyé, et non ce que Claude a lu. La compaction à un seuil de tokens et l’édition du contexte ne modifient que ce que Claude lit : elles ne comptent donc jamais. Après un bloc de compaction à seuil, l’API ne compare que les messages à partir de ce bloc, plus system et tools. La compaction à la demande a ses propres conditions : consultez Conditions pour que la réflexion conservée reste valide. Pour un fichier envoyé par URL et, sur la Claude API, une liste d’outils MCP, l’API compare plutôt ce qu’elle a récupéré.
• La réflexion que vous envoyez doit former une suite ininterrompue. Les blocs de réflexion ne sont pas comparés en tant que contenu. Mais chacun de ceux que vous envoyez, à l’exception du premier, doit avoir le même bloc de réflexion précédent que lorsque Claude l’a produit. Vous pouvez donc omettre le plus ancien, le plus récent ou tous, mais pas un bloc situé entre d’autres.

Une modification peut être aussi minime qu’un seul mot dans la description d’un outil. Modifier, insérer, déplacer ou supprimer un message antérieur compte, quel que soit son rôle. Il en va de même pour la modification du texte qui précède un bloc de réflexion dans son propre message.

Ce qui ne compte pas

Définir prefix_mismatch_behavior

L’en-tête bêta thinking-binding-controls-2026-08-01 ajoute le réglage thinking.block_binding.prefix_mismatch_behavior et le tableau input_transformations de la réponse.

Les blocs qui échouent à la vérification du préfixe restent invalides sur chaque requête ultérieure qui les envoie, tant que la modification est en place. Le réglage agit sur la seule requête qui le contient. Avec la réflexion désactivée ("disabled" ou "between_tools"), l’envoyer produit une erreur 400 sur tous les modèles.

La requête suivante définit prefix_mismatch_behavior sur "drop_block". Lors d’un premier tour, il n’y a aucune réflexion à renvoyer, donc input_transformations revient vide :

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    thinking={
        "type": "adaptive",
        "block_binding": {"prefix_mismatch_behavior": "drop_block"},
    },
    messages=[
        {
            "role": "user",
            "content": "What is the greatest common divisor of 1071 and 462?",
        }
    ],
    betas=["thinking-binding-controls-2026-08-01"],
)

for block in response.content:
    if block.type == "text":
        print(block.text)

print(f"Input transformations: {len(response.input_transformations or [])}")

Surveiller le trafic de production

Lorsque prefix_mismatch_behavior est omis, une requête qui échoue à la vérification du préfixe peut n’obtenir aucune erreur sur certains modèles. Les blocs de réflexion qui y ont échoué parviennent alors au modèle. Pour trouver ces blocs dans le trafic de production, envoyez l’en-tête bêta thinking-binding-controls-2026-08-01, omettez le réglage et journalisez le tableau input_transformations de chaque réponse. L’en-tête ajoute ce tableau et ne modifie pas ce que reçoit le modèle.

Chacun de ces blocs obtient sa propre entrée thinking_mismatch_allowed dans ce tableau. Une entrée se présente ainsi :

{
  "input_transformations": [
    {
      "type": "thinking_mismatch_allowed",
      "path": "messages.1.content.0",
      "reason": "prefix_binding_mismatch"
    }
  ]
}

Pour trouver la modification, consultez Trouver ce que votre code a modifié.

Déterminer quel cas vous obtenez

Sur certains modèles, une requête qui échoue à la vérification du préfixe peut obtenir l’erreur 400 ou aucune erreur. Ce test montre lequel des deux une requête obtient :

1. Prenez une conversation qui contient un bloc de réflexion provenant de l’un de ces modèles. Modifiez ou ajoutez l’invite système (system). Le bloc échoue alors à la vérification du préfixe, car l’invite système a changé après que Claude a produit le bloc.
2. Envoyez-la au même modèle avec l’en-tête bêta thinking-binding-controls-2026-08-01, et omettez prefix_mismatch_behavior.

La réponse est l’une des suivantes :

• Une erreur 400 qui indique bound to a different conversation : la requête a obtenu l’erreur 400.
• Une réponse 200 dont le tableau input_transformations contient des entrées thinking_mismatch_allowed : la requête n’a obtenu aucune erreur. Chaque entrée nomme un bloc de réflexion qui a échoué à la vérification du préfixe et a atteint Claude.
• Une réponse 200 dont le tableau input_transformations est vide : aucun bloc n’a échoué à la vérification du préfixe, donc le test ne montre rien. Assurez-vous que la conversation contient un bloc de réflexion provenant de ce modèle.

Le résultat décrit cette seule requête et ne garantit rien pour les suivantes : écrivez donc votre code de manière à gérer les deux cas.

Étapes suivantes