Erreurs de l'API Claude



Erreurs HTTP

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

• 400 - invalid_request_error : Il y a eu un problème avec le format ou le contenu de votre requête. Ce type d'erreur peut également être utilisé pour d'autres codes de statut 4XX non répertoriés dans cette section.

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

• 402 - billing_error : Il y a un problème avec vos informations de facturation ou de paiement. Vérifiez vos informations de paiement dans la Claude Console, ou dans AWS Marketplace si vous utilisez Claude Platform sur AWS.

• 403 - permission_error : Votre clé API n'a pas la permission 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 n'a pas été trouvée. Vérifiez le chemin du point de terminaison et tous les identifiants de ressources dans l'URL de la requête.

• 409 - conflict_error : La requête est 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 réessayez 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 compte a atteint une limite de débit.

• 500 - api_error : Une erreur inattendue s'est produite en interne dans les systèmes d'Anthropic. Réessayez la requête avec un backoff exponentiel ; si l'erreur persiste, contactez le support avec l'identifiant de requête.

• 504 - timeout_error : La requête a expiré pendant le 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.

Les SDK officiels réessaient automatiquement les échecs transitoires (tels que les erreurs de connexion, les limites de débit et les erreurs serveur 5xx) avec un backoff exponentiel, deux fois par défaut, en respectant l'en-tête retry-after lorsqu'il est présent. Chaque client SDK accepte une option de nombre maximal de tentatives 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 se produire 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 en cours de flux.



Limites de taille des requêtes

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

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



Structure 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 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 versionnage, les valeurs au sein de ces objets peuvent s'étendre, et il est possible que les valeurs de type augmentent 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, et les noms de classes et les espaces de noms diffèrent selon le langage. Par exemple, une erreur 404 apparaît comme anthropic.NotFoundError en Python, Anthropic::Errors::NotFoundError en Ruby, com.anthropic.errors.NotFoundException en Java, et comme une valeur unique *anthropic.Error (avec un branchement sur StatusCode) en Go. Interceptez les classes typées du SDK plutôt que de faire correspondre des chaînes de caractères dans les messages d'erreur, en traitant d'abord les classes les plus spécifiques. Chaque page de 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 sur 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, qui vous permettent également de lire tout autre en-tête de réponse. Sur Claude Platform sur AWS, utilisez l'accesseur de réponse brute pour lire également 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 sur Claude Platform sur 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 période de temps variable, ce qui peut faire échouer la requête ou provoquer son expiration 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 expirations de connexions inactives sur certains réseaux.

Les SDK valident que vos requêtes non-streaming vers 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, 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 Streaming de messages 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 en cause (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, 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 Sortie de réflexion sur Claude Fable 5 et Claude Mythos 5.



Réflexion étendue non prise en charge

Les modèles Claude 4.7 et ultérieurs ont supprimé la 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, Claude Mythos 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 :

"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 Fable 5 et Claude Mythos 5, la suggestion "thinking.type.enabled" contenue dans le message d'erreur lui-même est également rejetée. 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 la réflexion. Consultez Dépannage de la réflexion.



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

Si chaque requête vers Claude Platform sur 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.



Prochaines étapes