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 listé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. Les limites sur l'espace de travail Claude Code font exception et peuvent renvoyer une erreur 429 à la place.

• 401 - authentication_error : Votre « API key » (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, cette erreur 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 paramètres d'accès et d'espace de travail de votre organisation dans la Claude Console.

• 404 - not_found_error : La ressource demandée est introuvable. Vérifiez le chemin du point de terminaison et tous 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 connaître les maximums par point de terminaison.

• 429 - rate_limit_error : Votre organisation a atteint l'une des limites suivantes : 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 ne comporte pas d'en-tête retry-after et continue d'échouer jusqu'à la reprise de l'accès. 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 internes 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 : Le délai de traitement de la requête a expiré. Envisagez d'utiliser l'API Messages en streaming pour les requêtes de longue durée. Consultez Requêtes longues pour découvrir d'autres options.

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

Les SDK officiels relancent 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. Ils effectuent deux nouvelles tentatives par défaut et respectent l'en-tête retry-after lorsqu'il est présent. Le client 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 forme 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 des SDK

Les SDK officiels lèvent des exceptions typées pour ces erreurs au lieu de renvoyer du JSON brut. Les noms de classes et les espaces de noms diffèrent selon le langage. Par exemple, une erreur 404 apparaît sous la forme anthropic.NotFoundError. Le SDK Go utilise 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 le texte des messages d'erreur, en traitant d'abord les classes les plus spécifiques. La page de chaque SDK documente sa hiérarchie complète d'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.
• Les réseaux diffèrent en fiabilité. L'API Message Batches peut vous aider à gérer le risque de problèmes réseau en vous permettant d'interroger les résultats plutôt que d'exiger une connexion réseau ininterrompue.

Si vous construisez 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 censées 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, les SDK peuvent 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 d'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 l'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 à l'exception de Claude Mythos Preview, le message est le suivant :

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

Omettez le paramètre thinking et la requête s'exécutera 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 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 renvoie une erreur 400 invalid_request_error, y compris sur le point de terminaison de comptage de tokens :

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

Les valeurs tool_choice: {"type": "auto"} (la valeur par défaut) et {"type": "none"} sont acceptées. 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 la réponse elle-même doit respecter une structure JSON fixe. Consultez Forcer l'utilisation d'outils.

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

Sur la Claude API et Google Cloud, Claude Opus 5.5 prend en charge le « computer use » (utilisation de l'ordinateur) uniquement sous la forme de l'ensemble d'outils computer_toolset_20260801. Sur ces plateformes, si vous lui envoyez une entrée tools du type antérieur computer_20251124 (avec l'en-tête bêta de cet outil), vous recevez une erreur 400 invalid_request_error. Le message indique le type rejeté, puis liste après Did you mean one of les types d'outils que le modèle accepte. Il commence ainsi :

'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, puis mettez à jour votre boucle d'agent comme décrit dans Migrer depuis computer_20251124. Les modèles antérieurs qui prennent en charge l'ensemble d'outils continuent d'accepter computer_20251124, tout comme Claude Opus 5.5 sur Amazon Bedrock.

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

Sur Claude Fable 5.1 et Claude Opus 5.5, l'API n'accepte un bloc de réflexion rejoué que si le prompt system, les tools et les messages qui le précèdent sont inchangés. Si l'historique antérieur d'un bloc rejoué a changé, ce bloc est rejeté avec une erreur 400 invalid_request_error. Cela s'applique aux nouveaux comptes créés à partir du 31 août 2026, ainsi qu'à toute requête qui définit thinking.block_binding.prefix_mismatch_behavior sur "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. 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