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.

  Une erreur 401 dont le message commence par CORS requests are not allowed for this Organization ne provient pas d’un problème lié à votre clé API. La requête incluait un en-tête Origin, que les navigateurs ajoutent, et votre organisation ne peut pas appeler la Claude API directement depuis un navigateur. Le message se poursuit par because of custom retention settings ou because of its settings. Le premier n’apparaît que pour les dispositifs de conservation des données tels que la « zero data retention » (conservation zéro des données), ou ZDR ; le second correspond au cas général, qui inclut la Compliance API. Aucune modification de la requête du navigateur ne permet de résoudre ce problème. Envoyez donc la requête depuis votre propre back-end ; consultez Applications basées sur le navigateur.

• 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. Si le type d’erreur est timeout_error à la place, consultez l’entrée 504.

• 504 - timeout_error : La requête a expiré pendant son traitement. L’API renvoie également timeout_error avec d’autres codes de statut, comme une erreur 500 lorsqu’une requête atteint la limite de temps du serveur avant que la réponse ne commence. Pour les requêtes de longue durée à l’API Messages, utilisez l’API Messages en streaming. 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

La Claude API propriétaire applique ces limites de taille des requêtes. Pour les autres plateformes, consultez la présentation de l’API.

Si vous dépassez ces limites, vous recevrez une erreur 413 request_too_large. Sur la Claude API propriétaire, 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 BatchesAperçu disponible avec des liens vers la référence de l’API, appuyez sur Tab jusqu’à ce que le focus entre dans la carte, et sur Échap pour revenir. :

• 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 BatchesAperçu disponible avec des liens vers la référence de l’API, appuyez sur Tab jusqu’à ce que le focus entre dans la carte, et sur Échap pour revenir. 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.

Le SDK Claude vérifie que vos requêtes non-streaming à l’API Messages ne sont pas censées dépasser un délai d’expiration de 10 minutes. Il définit é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 Obtenir le message final sans gérer les événements 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’utilisation d’outils, renvoyez chaque bloc thinking et redacted_thinking du tour de l’assistant exactement tel que reçu, y compris les blocs dont le champ thinking est vide. Si votre application filtre les blocs de contenu par type avant de les renvoyer, incluez à la fois thinking et redacted_thinking. Consultez la correction pour les blocs de réflexion modifiés dans Dépannage de la réflexion, ainsi que Préserver les 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 ne prennent pas en charge 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. Migrer vers la réflexion adaptative présente la correspondance des paramètres, et Dépannage de la réflexion couvre la correction axée sur les symptômes pour l’erreur de réflexion étendue.

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 la correction axée sur les symptômes pour l’erreur de réflexion adaptative dans Dépannage de la réflexion.

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

Sur Claude Fable 5.2, Claude Mythos 5.2, 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 également "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 les erreurs between_tools et d’effort dans Dépannage de la réflexion.

Omettez le paramètre thinking et 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 la correction pour l’erreur de réflexion désactivée dans Dépannage de la réflexion.

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

Claude Fable 5.2, Claude Mythos 5.2, 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

Claude Fable 5.2, Claude Mythos 5.2, Claude Opus 5.5, Claude Sonnet 5.5 et Claude Haiku 5.5 renvoient une erreur 400 pour toute version de l’outil d’utilisation de l’ordinateur qu’ils n’acceptent pas. Sur l’API Claude, cela inclut computer_20251124 avec son en-tête bêta. Ils n’acceptent computer_20250124 sur aucune plateforme. Le message invalid_request_error de l’API Claude indique le type rejeté et, après Did you mean one of, liste les types d’outils que le modèle accepte. Pour Claude Opus 5.5, le message commence par :

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

L’API Claude renvoie le même message pour tout type d’outil défini par Anthropic que le modèle demandé ne prend pas en charge. Claude Fable 5.2, Claude Mythos 5.2, Claude Opus 5.5, Claude Sonnet 5.5 et Claude Haiku 5.5 prennent en charge l’utilisation de l’ordinateur via l’ensemble d’outils computer_toolset_20260801. 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 Passer l’utilisation de l’ordinateur à l’ensemble d’outils dans le guide de migration de Claude Haiku 5.5.

Sur Amazon Bedrock, Claude Fable 5.2, Claude Mythos 5.2, Claude Opus 5.5, Claude Sonnet 5.5 et Claude Haiku 5.5 acceptent également l’outil computer_20251124 avec l’en-tête bêta computer-use-2025-11-24. Versions antérieures de l’outil liste les modèles à utiliser avec chaque version antérieure.

Bloc de réflexion lié à une autre conversation

Cette erreur 400 invalid_request_error signifie généralement qu’un bloc de réflexion que vous avez renvoyé a échoué à la vérification du préfixe : un élément situé avant le bloc a changé après la production de ce bloc, comme l’invite système system, les tools ou un message antérieur. Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Sonnet 5.5 et Claude Haiku 5.5 effectuent cette vérification. Pour les requêtes qui ne définissent pas prefix_mismatch_behavior, Lorsque prefix_mismatch_behavior n’est pas défini indique lesquelles reçoivent cette erreur. 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 nomme également cet en-tête. Renvoyer le même historique échoue de la même manière, même après avoir corrigé le code à l’origine de la modification. Pour poursuivre la conversation, envoyez l’en-tête bêta avec prefix_mismatch_behavior: "drop_block" lors de la nouvelle tentative et de chaque requête ultérieure. Vous pouvez également supprimer le bloc nommé par l’erreur ainsi que chaque bloc thinking et redacted_thinking ultérieur, puis réessayer une fois. Sur Claude Sonnet 5.5 et Claude Haiku 5.5, block_binding ne fonctionne qu’avec thinking: {"type": "adaptive"} ; avec tout autre paramètre de réflexion, supprimez donc les blocs. Pour éviter que les nouvelles conversations n’échouent, conservez l’historique en mode ajout uniquement. Un bloc provenant d’un modèle que le modèle cible ne peut pas lire est ignoré plutôt que rejeté. Consultez Conserver le préfixe inchangé et la correction pour une signature de bloc de réflexion invalide dans 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 pour chaque compte AWS. Consultez Activer la fédération d’identité web sortante pour plus de détails.

Étapes suivantes