Aller au contenu
Cercle IA Tech · API Un site du réseau Cercle IA Tech

Guide

Réponse coupée : lire le stop_reason d'une API

Pourquoi une réponse de Claude s'arrête en plein milieu : max_tokens, contexte, refus, outil. Les valeurs de stop_reason et la suite à donner.

Mis à jour le

Quand la réponse d'un modèle s'arrête au milieu d'une phrase, le texte lui-même ne dit pas pourquoi. L'explication est dans un champ de la réponse : stop_reason, la raison de l'arrêt. La documentation de Claude relue pour cette page décrit sept valeurs principales. Les lire est la première chose à faire avant de chercher un bug ailleurs. Informations relevées le 16/11/2026.

Si votre application dialogue avec une plateforme d’assistants, la documentation API d’ALMA aide à examiner le format de réponse exposé au client. N’attendez pas nécessairement un champ identique à celui de Claude : traitez les états documentés par l’interface réellement appelée.

Les sept valeurs et la suite à donner

stop_reason Sens (documentation Anthropic) Que faire
end_turn Claude a terminé sa réponse naturellement Vérifier le contenu avant son utilisation
max_tokens La réponse a atteint votre limite max_tokens Augmenter max_tokens ou demander la suite
stop_sequence Claude a émis l'une de vos stop_sequences Lire stop_sequence pour savoir laquelle
tool_use Claude appelle un outil Contrôler droits et arguments, exécuter si autorisé, renvoyer le résultat
pause_turn Une boucle d'outils côté serveur a atteint sa limite d'itérations Renvoyer le contenu de l'assistant pour continuer
refusal Claude a refusé de répondre Lire stop_details, réessayer éventuellement avec un autre modèle
model_context_window_exceeded La réponse a rempli la fenêtre de contexte du modèle Traiter la réponse comme tronquée

Cas 1 : la limite de sortie max_tokens

Votre limite de longueur est atteinte. La page sur la réduction de latence prévient que l'API coupe alors la réponse, « perhaps mid-sentence or mid-word » (peut-être en pleine phrase ou en plein mot), et que c'est une technique brutale qui peut demander un retraitement ; elle convient surtout aux réponses courtes, comme un choix multiple. Si la réponse doit être longue, relevez la limite. La page des raisons d'arrêt signale un piège : si le dernier bloc est un appel d'outil (tool_use) coupé net, il faut relancer avec une limite plus haute. Extrait adapté de la documentation, avec contrôle de présence d’un bloc :

if response.stop_reason == "max_tokens" and response.content:
    # Check if the last content block is an incomplete tool_use
    last_block = response.content[-1]
    if last_block.type == "tool_use":
        # Send the request with higher max_tokens
        response = client.messages.create(
            model="claude-opus-5-5",
            max_tokens=4096,  # Increased limit
            messages=messages,
            tools=tools,
        )

Chez Mistral, la référence du point d'accès précise que le nombre de jetons du prompt plus max_tokens ne peut pas dépasser la longueur de contexte du modèle.

Cas 2 : model_context_window_exceeded

La réponse a rempli la fenêtre de contexte avant d'atteindre max_tokens. Selon la documentation, cette valeur permet de demander le maximum de jetons sans connaître la taille exacte de l'entrée ; la réponse est alors à traiter comme tronquée. La page précise que cette valeur est typée seulement dans l'espace beta du SDK, et qu'il faut un en-tête bêta pour les modèles antérieurs à Sonnet 4.5.

Cas 3 : refusal, une réponse 200

Piège fréquent : un refus n'est pas une erreur. La documentation indique que les classificateurs de sécurité renvoient cette valeur « dans une réponse HTTP 200 normale, pas dans une erreur ». Le champ stop_details indique la catégorie de règle ; il vaut null pour toutes les autres raisons d'arrêt. La page ajoute qu'on peut généralement obtenir une réponse en réessayant avec un autre modèle Claude, et que Claude Haiku 5.5 demande une reprise côté client.

Cas 4 : outils (tool_use, pause_turn)

Dans une boucle d'outils, un arrêt n'est pas une fin. Avec tool_use, la page indique que le message utilisateur suivant ne doit contenir que des blocs tool_result : ajouter autre chose après eux, par exemple du texte, termine le tour de l'assistant. Pour pause_turn, la limite par défaut est de 10 itérations par requête. Le détail des outils est traité sur la page appel de fonction du site Agents.

Reprendre sans masquer une réponse incomplète

Pour un texte, une demande de continuation peut répéter un passage ou modifier la structure. Pour un objet JSON, ne concaténez pas aveuglément deux fragments : vérifiez le document complet après reprise, puis son contenu métier. Pour un appel d’outil tronqué, n’exécutez pas les arguments incomplets.

Enregistrez le motif d’arrêt, le modèle et les compteurs d’usage. Affichez « réponse partielle » si la tâche n’est pas terminée, plutôt que de présenter le dernier fragment comme un résultat final. Une reprise doit rester limitée en tours, en durée et en budget. Si le contexte est plein, augmenter seulement la limite de sortie ne crée pas de place supplémentaire : réduisez l’historique ou découpez le travail.

Erreurs et raisons d’arrêt : deux choses

stop_reason arrive dans une réponse réussie. Un échec est une réponse HTTP 4xx ou 5xx avec détail d'erreur. Vérifiez donc stop_reason seulement après un appel réussi, et traitez les échecs avec les codes d'erreur de l'API Claude. Pour les limites de débit, voir l'erreur 429 ; pour afficher la réponse au fil de l'eau, le streaming.

Questions fréquentes

Pourquoi la réponse de l'API s'arrête-t-elle au milieu d'une phrase ?

Elle peut avoir atteint la limite max_tokens que vous avez fixée : l'API coupe alors la réponse, parfois en pleine phrase ou en plein mot. Le champ stop_reason vaut max_tokens.

Un refus de Claude est-il une erreur HTTP ?

Non. Les classificateurs de sécurité renvoient stop_reason refusal dans une réponse HTTP 200 normale, pas dans une erreur. Le champ stop_details précise la catégorie de règle concernée.

Faut-il vérifier stop_reason avant de lire le texte ?

Oui, après un appel réussi. Les échecs, eux, sont des réponses HTTP 4xx ou 5xx avec un détail d'erreur : ce sont deux mécanismes distincts.

Sources

Pages consultées pour écrire cet article :

  1. https://alma.iarche.fr/fr/api-docs
  2. https://platform.claude.com/docs/en/build-with-claude/handling-stop-reasons
  3. https://platform.claude.com/docs/en/test-and-evaluate/strengthen-guardrails/reduce-latency
  4. https://docs.mistral.ai/api/endpoint/chat

À lire aussi