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 erreurs 529 peuvent se produire lorsque l'API connaît un trafic élevé pour l'ensemble des utilisateurs.

  Dans de rares cas, si votre organisation connaît une forte augmentation de son utilisation, vous pourriez voir des erreurs 429 en raison des limites d'accélération de l'API. Pour éviter d'atteindre les limites d'accélération, augmentez votre trafic progressivement et maintenez des schémas d'utilisation cohérents.

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 événements envoyés par le serveur (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 forme 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.



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 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 les messages d'erreur par chaînes de caractères, en gérant 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 à propos 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 API directe, 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 valident 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(message.content[0].text)

Consultez Messages en streaming pour plus de détails.



Erreurs de validation courantes



Préremplissage non pris en charge

Claude Fable 5, Claude Mythos 5, Claude Mythos Preview, Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6 et Claude Sonnet 4.6 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": "Prefilling assistant messages is not supported for this model."
  }
}

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'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 Préservation des blocs de réflexion et Sortie de réflexion sur Claude Fable 5 et Claude Mythos 5.



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