Erreurs de la Claude API

Erreurs HTTP

L'API suit un format de codes d'erreur HTTP prévisible :

• 400 - invalid_request_error : Le format ou le contenu de votre requête pose problème. Ce type d'erreur peut également être utilisé pour d'autres codes de statut 4XX non répertoriés dans cette section. L'API renvoie également une erreur 400 lorsque l'utilisation atteint une limite de dépenses que vous avez définie pour une organisation ou un espace de travail, à l'exception des limites sur l'espace de travail Claude Code, qui peuvent renvoyer une erreur 429 à la place.

• 401 - authentication_error : Votre clé API pose problème (par exemple, elle est mal formée, révoquée ou expirée ; consultez Expiration des clés). Sur Claude Platform on AWS, cela peut également indiquer un problème avec vos identifiants AWS ou votre signature SigV4.

• 402 - billing_error : Vos informations de facturation ou de paiement posent problème. Vérifiez vos informations de paiement dans la Claude Console, ou dans AWS Marketplace si vous utilisez Claude Platform on AWS.

• 403 - permission_error : Votre clé API n'a pas l'autorisation d'utiliser la ressource spécifiée. Vérifiez les accès de votre organisation et les paramètres de l'espace de travail dans la Claude Console.

• 404 - not_found_error : La ressource demandée est introuvable. Vérifiez le chemin du point de terminaison et les identifiants de ressource dans l'URL de la requête.

• 409 - conflict_error : La requête entre en conflit avec l'état actuel d'une ressource. Par exemple, la ressource a été modifiée simultanément, ou une valeur qui doit être unique est déjà utilisée. Résolvez le conflit, puis relancez la requête.

• 413 - request_too_large : La requête dépasse le nombre maximal d'octets autorisé. Consultez Limites de taille des requêtes pour les maximums par point de terminaison.

• 429 - rate_limit_error : Votre organisation a atteint une « rate limit » (limite de débit), le plafond de dépenses mensuel de son niveau d'utilisation, ou une limite de dépenses sur l'espace de travail Claude Code. Une erreur 429 liée au plafond de dépenses du niveau n'a pas d'en-tête retry-after et continue d'échouer jusqu'à ce que l'accès reprenne ; consultez Atteindre votre plafond de dépenses pour savoir comment la reconnaître.

• 500 - api_error : Une erreur inattendue s'est produite dans les systèmes d'Anthropic. Relancez la requête avec un « exponential backoff » (délai d'attente exponentiel) ; si l'erreur persiste, contactez le support en fournissant l'identifiant de requête.

• 504 - timeout_error : La requête a expiré pendant son traitement. Envisagez d'utiliser l'API Messages en streaming pour les requêtes de longue durée. Consultez Requêtes longues pour plus d'options.

• 529 - overloaded_error : L'API est temporairement surchargée.

Le SDK officiel relance automatiquement les requêtes en cas d'échec transitoire (erreurs de connexion, limites de débit ou erreurs serveur 5xx, par exemple) avec un délai d'attente exponentiel, deux fois par défaut, en respectant l'en-tête retry-after lorsqu'il est présent. Le client du SDK accepte max_retries pour configurer ou désactiver ce comportement.

Lors de la réception d'une réponse en streaming via des « server-sent events » (événements envoyés par le serveur), ou SSE, une erreur peut survenir après que l'API a renvoyé une réponse 200. Dans ce cas, la gestion des erreurs ne suit pas ces mécanismes standard. Consultez Événements d'erreur pour la structure des erreurs survenant en cours de flux.

Limites de taille des requêtes

L'API applique des limites de taille de requête :

Si vous dépassez ces limites, vous recevrez une erreur 413 request_too_large. Sur la Claude API directe, Cloudflare renvoie cette erreur avant que la requête n'atteigne les serveurs de l'API.

Formes des erreurs

L'API renvoie toujours les erreurs au format JSON, avec un objet error de premier niveau qui inclut toujours une valeur type et une valeur message. La réponse inclut également un champ request_id pour faciliter le suivi et le débogage. Par exemple :

{
  "type": "error",
  "error": {
    "type": "not_found_error",
    "message": "The requested resource could not be found."
  },
  "request_id": "req_011CSHoEeqs5C35K2UUqR7Fy"
}

Conformément à la politique de gestion des versions, les valeurs contenues dans ces objets peuvent s'étendre, et il est possible que les valeurs de type s'enrichissent au fil du temps.

Types d'erreurs du SDK

Le SDK officiel lève des exceptions typées pour ces erreurs au lieu de renvoyer du JSON brut. Par exemple, une erreur 404 apparaît sous la forme anthropic.NotFoundError. Le SDK Go possède un seul type d'erreur pour tous les statuts, *anthropic.Error : effectuez un branchement sur StatusCode. Interceptez les classes typées du SDK plutôt que de comparer les chaînes des messages d'erreur, en traitant d'abord les classes les plus spécifiques. La page de votre SDK documente la hiérarchie complète des exceptions :

• Python · TypeScript · C# · Go · Java · PHP · Ruby

Identifiant de requête

Chaque réponse de l'API inclut un en-tête request-id unique. Cet en-tête contient une valeur telle que req_018EeWyXxfu5pfWkrYcMdjWG. Le même identifiant apparaît dans le champ request_id des corps de réponse d'erreur. Lorsque vous contactez le support au sujet d'une requête spécifique, incluez cet identifiant pour aider à résoudre rapidement votre problème.

Sur Claude Platform on AWS, les réponses incluent deux identifiants de requête : l'identifiant de requête AWS (x-amzn-requestid, principal, indexé dans CloudTrail) et l'identifiant de requête Anthropic (request-id, secondaire). Utilisez l'identifiant de requête AWS pour les recherches dans CloudTrail et l'identifiant de requête Anthropic pour les tickets de support Anthropic.

Les SDK Python et TypeScript exposent l'identifiant de requête sous la forme d'une propriété _request_id sur les objets de réponse de premier niveau. Les SDK C#, Go, Java et PHP l'exposent via leurs accesseurs de réponse brute, et le SDK Ruby via un middleware. Dans tous les SDK sauf Ruby, utilisez with_raw_response pour lire tout autre en-tête de réponse, comme anthropic-organization-id et anthropic-workspace-id. En Ruby, utilisez le même middleware. Sur Claude Platform on AWS, utilisez également l'accesseur de réponse brute pour lire l'identifiant de requête AWS (x-amzn-requestid) :

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(f"Request ID: {message._request_id}")

Pour des exemples d'identifiants de requête Claude Platform on AWS dans d'autres langages, consultez Identifiants de requête.

Requêtes longues

Évitez de définir une valeur max_tokens élevée sans utiliser l'API Messages en streaming ou l'API Message Batches :

• Certains réseaux peuvent interrompre les connexions inactives après une durée variable, ce qui peut entraîner l'échec ou l'expiration de la requête sans recevoir de réponse d'Anthropic.
• La fiabilité varie selon les réseaux. L'API Message Batches peut vous aider à gérer le risque de problèmes réseau en vous permettant d'interroger périodiquement les résultats plutôt que d'exiger une connexion réseau ininterrompue.

Si vous développez une intégration directe avec l'API, la configuration d'un keep-alive de socket TCP peut réduire l'impact des délais d'expiration des connexions inactives sur certains réseaux.

Les SDK vérifient que vos requêtes non-streaming à l'API Messages ne sont pas susceptibles de dépasser un délai d'expiration de 10 minutes. Ils définissent également une option de socket pour le keep-alive TCP.

Si vous n'avez pas besoin de traiter les événements de manière incrémentale, le SDK peut consommer le flux pour vous et renvoyer l'objet Message complet, identique à ce que renvoie un appel non-streaming :

client = anthropic.Anthropic()

with client.messages.stream(
    max_tokens=128000,
    messages=[{"role": "user", "content": "Write a detailed analysis..."}],
    model="claude-sonnet-5",
) as stream:
    message = stream.get_final_message()

print(next(block.text for block in message.content if block.type == "text"))

Consultez Messages en streaming pour plus de détails.

Erreurs de validation courantes

Préremplissage non pris en charge

Les modèles Claude 4.6 et ultérieurs ainsi que Claude Mythos Preview ne prennent pas en charge le préremplissage des messages de l'assistant. L'envoi d'une requête avec un dernier message de l'assistant prérempli à l'un de ces modèles renvoie une erreur 400 invalid_request_error :

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "This model does not support assistant message prefill. The conversation must end with a user message."
  }
}

Utilisez plutôt les sorties structurées sur les modèles qui les prennent en charge, des instructions dans le « system prompt » (invite système), ou output_config.format.

Les blocs de réflexion ne peuvent pas être modifiés

Si le message d'assistant le plus récent contient des blocs thinking ou redacted_thinking qui ont été modifiés, réordonnés, filtrés ou reconstruits avant d'être renvoyés à l'API, la requête renvoie une erreur 400 invalid_request_error. Le message d'erreur commence par la position du bloc fautif (par exemple, messages.1.content.0) et contient :

`thinking` or `redacted_thinking` blocks in the latest assistant message cannot be modified. These blocks must remain as they were in the original response.

Avec l'« tool use » (utilisation d'outils), chaque bloc thinking et redacted_thinking du tour de l'assistant doit être renvoyé exactement tel qu'il a été reçu, y compris les blocs dont le champ thinking est vide. Renvoyez les blocs de réflexion sans modification, et si votre application filtre les blocs de contenu par type avant de les renvoyer, incluez à la fois thinking et redacted_thinking. Consultez Dépannage de la réflexion, Préservation des blocs de réflexion et Réflexion préservée.

Réflexion étendue non prise en charge

Les modèles Claude 4.7 et ultérieurs ont supprimé l'« extended thinking » (réflexion étendue). L'envoi de thinking: {"type": "enabled"} à l'un de ces modèles renvoie une erreur 400 invalid_request_error :

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

Utilisez plutôt la réflexion adaptative. Migration vers la réflexion adaptative présente la correspondance des paramètres, et Dépannage de la réflexion couvre la correction à partir du symptôme.

Réflexion adaptative non prise en charge

Les modèles qui ne prennent en charge que la réflexion étendue (Claude 4.5 et modèles antérieurs) rejettent thinking: {"type": "adaptive"} avec une erreur 400 invalid_request_error :

adaptive thinking is not supported on this model

Utilisez thinking: {"type": "enabled", "budget_tokens": N} sur ces modèles ; consultez Réflexion étendue pour la configuration et Dépannage de la réflexion pour la correction à partir du symptôme.

La réflexion ne peut pas être désactivée

Sur Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Opus 5.5 et Claude Mythos Preview, la réflexion est toujours activée. L'envoi de thinking: {"type": "disabled"} à l'un de ces modèles renvoie une erreur 400 invalid_request_error. Sur tous ces modèles sauf Claude Mythos Preview, le message indique :

"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 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.

Sur Claude Sonnet 5.5, la réflexion ne peut pas être définie sur disabled. Utilisez thinking: {"type": "between_tools"} pour le réglage de réflexion le plus bas, qui désactive la réflexion préalable. L'envoi de thinking: {"type": "disabled"} renvoie une erreur 400 invalid_request_error avec ce message :

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.

Avec un effort xhigh ou max, une requête avec between_tools renvoie également une erreur 400 invalid_request_error. Le message indique que la réflexion est désactivée, car between_tools n'a pas de réflexion préalable :

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

Avec between_tools, l'effort ne peut pas changer en cours de conversation : un output_config.effort par message qui diffère du niveau en vigueur renvoie une erreur 400. L'erreur indique la position du message qui a défini le nouveau niveau :

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.

Claude Haiku 5.5 accepte thinking: {"type": "disabled"} et le soumet aux deux mêmes limites d'effort que celles qui s'appliquent à between_tools : avec un effort xhigh ou max, ou avec un output_config.effort par message qui diffère du niveau en vigueur, la requête renvoie une erreur 400 invalid_request_error avec le message correspondant présenté plus haut.

Dans les deux messages, « enable thinking » désigne la réflexion adaptative : omettez le champ thinking ou envoyez thinking: {"type": "adaptive"}. Claude Sonnet 5.5 et Claude Haiku 5.5 rejettent "enabled" avec une erreur 400. Pour faire varier l'effort à chaque tour, utilisez la réflexion adaptative.

L'envoi de thinking: {"type": "between_tools"} à tout modèle autre que Claude Sonnet 5.5 renvoie une erreur 400 invalid_request_error :

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

Pour les corrections, consultez Dépannage de la réflexion, qui couvre les erreurs liées à between_tools et à l'effort.

Si vous omettez le paramètre thinking, la requête s'exécute avec la réflexion adaptative. Pour exclure le contenu de réflexion des réponses sans désactiver la réflexion, définissez display: "omitted" dans la configuration de réflexion. Consultez Dépannage de la réflexion.

Utilisation forcée d'outils non prise en charge

Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.1 et Claude Mythos 5.1 ne prennent pas en charge l'utilisation forcée d'outils. L'envoi de tool_choice: {"type": "any"} ou de tool_choice: {"type": "tool", "name": "..."} à l'un de ces modèles, y compris sur le point de terminaison de comptage de tokens, renvoie une erreur 400 invalid_request_error :

tool_choice: type "tool" and "any" are not supported for this model.

tool_choice: {"type": "auto"} (la valeur par défaut) et {"type": "none"} sont acceptés. Utilisez auto avec l'utilisation d'outils stricte pour que les entrées des outils restent conformes au schéma, ou les sorties structurées lorsque vous avez besoin que la réponse elle-même ait une structure JSON fixe. Consultez Forcer l'utilisation d'outils.

Version de l'outil d'utilisation de l'ordinateur non prise en charge

Sur l'API Claude et Google Cloud, Claude Opus 5.5, Claude Sonnet 5.5 et Claude Haiku 5.5 prennent en charge le « computer use » (utilisation de l'ordinateur) uniquement sous la forme du toolset computer_toolset_20260801. Sur ces plateformes, l'envoi à l'un de ces modèles d'une entrée tools de l'ancien type computer_20251124 ou computer_20250124, avec l'en-tête bêta de cet outil, renvoie une erreur 400 invalid_request_error. Le message indique le type rejeté, puis liste les types d'outils que le modèle accepte après Did you mean one of. Pour Claude Opus 5.5, il commence par :

'claude-opus-5-5' does not support tool types: computer_20251124.

L'API renvoie le même message pour tout type d'outil défini par Anthropic que le modèle demandé ne prend pas en charge. Déclarez {"type": "computer_toolset_20260801"} sans l'en-tête bêta et mettez à jour votre boucle d'agent comme décrit dans Migrer depuis computer_20251124. Pour migrer depuis computer_20250124, consultez Faire passer l'utilisation de l'ordinateur à l'ensemble d'outils dans le guide de migration de Claude Haiku 5.5. Les modèles antérieurs qui prennent en charge le toolset continuent d'accepter computer_20251124, tout comme Claude Opus 5.5, Claude Sonnet 5.5 et Claude Haiku 5.5 sur Amazon Bedrock.

Le bloc de réflexion ne correspond plus à la conversation

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 le prompt system, les tools et les messages qui le précédaient restent inchangés. 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 sur "error", un bloc rejoué dont l'historique antérieur a changé est rejeté avec une erreur 400 invalid_request_error (avec "drop_block", l'API supprime le bloc et la requête réussit). Le message commence par la position du premier bloc en échec :

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".

Sans l'en-tête bêta thinking-binding-controls-2026-08-01, le message mentionne également cet en-tête. Conservez un historique de conversation en ajout seul, ou envoyez l'en-tête bêta avec prefix_mismatch_behavior: "drop_block" pour supprimer le bloc et continuer. Sur Claude Sonnet 5.5 et Claude Haiku 5.5, block_binding ne fonctionne qu'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 retirez 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 est supprimé plutôt que rejeté. Consultez Conserver le préfixe inchangé et Dépannage de la réflexion.

L'envoi de thinking.block_binding sans l'en-tête bêta thinking-binding-controls-2026-08-01 renvoie une erreur 400 invalid_request_error dont le message se termine par :

block_binding: Extra inputs are not permitted

Ajoutez l'en-tête, ou supprimez le champ.

Fédération d'identité web sortante désactivée (Claude Platform on AWS)

Si chaque requête vers Claude Platform on AWS renvoie "Outbound web identity federation is disabled for your account", exécutez aws iam enable-outbound-web-identity-federation une fois par compte AWS. Consultez Activer la fédération d'identité web sortante pour plus de détails.

Étapes suivantes