Aller au contenu
Cercle IA Tech · API Un site du réseau Cercle IA Tech

Guide

Codes d'erreur de l'API Claude : 400, 401, 413, 529

Chaque code HTTP de l'API Claude, son type d'erreur, ce qu'on peut réessayer, les tailles maximales de requête et le request-id.

Mis à jour le

Quand l'API de Claude refuse un appel, elle répond par un code HTTP et un petit objet JSON qui contient un type et un message. Ce guide reprend la liste officielle, relevée le 16/11/2026 sur la page des erreurs de l'API, pour savoir quoi corriger et quoi réessayer. Pour le code 429 en particulier, voir la page dédiée aux limites de débit.

Les codes et leur sens

Code Type Ce que dit la documentation
400 invalid_request_error Problème de format ou de contenu de la requête ; aussi renvoyé quand une limite de dépense fixée par vous est atteinte
401 authentication_error Problème de clé d'API : mal formée, révoquée ou expirée
402 billing_error Problème de facturation ou de moyen de paiement
403 permission_error La clé n'a pas le droit d'utiliser la ressource demandée
404 not_found_error Ressource introuvable : vérifier le chemin et les identifiants
409 conflict_error Conflit avec l'état d'une ressource ; résoudre puis réessayer
413 request_too_large Requête au-delà du nombre d'octets autorisé
429 rate_limit_error Débit, plafond mensuel du palier ou limite de dépense de l’espace Claude Code
500 api_error Erreur interne chez Anthropic : réessayer avec attente exponentielle
504 timeout_error Délai dépassé pendant le traitement
529 overloaded_error API temporairement surchargée

Ce qu'on corrige, ce qu'on réessaie

  • 400, 401, 402, 403, 404, 413 : réessayer à l'identique ne changera rien, il faut corriger la requête, la clé, la facturation ou le chemin. Une limite de dépense d’organisation ou d’espace de travail donne normalement 400 ; la documentation cite une exception pour l’espace Claude Code, qui peut renvoyer 429. Sur la protection de la clé, voir comment la protéger.
  • 500, 504, 529 : des problèmes de côté serveur ; la documentation conseille pour la 500 de réessayer avec attente exponentielle et, si l'erreur persiste, de contacter le support avec le request-id.
  • Cas particulier d'un 401 en navigateur : un message commençant par « CORS requests are not allowed for this Organization » n'est pas un problème de clé. La requête contenait un en-tête Origin que les navigateurs ajoutent, et votre organisation ne peut pas appeler l'API directement depuis un navigateur ; la seule solution est d'envoyer l'appel depuis votre serveur.

Ne pas mélanger les contrats d’erreur

La documentation de l’API ALMA décrit un autre contrat d’intégration. Si votre application passe par une plateforme, vérifiez les réponses de cette plateforme avant d’appliquer le tableau Claude : un intermédiaire peut transformer le code, le message ou l’identifiant de suivi. Conservez la couche qui a renvoyé l’erreur dans votre journal technique.

Tailles maximales d’une requête

Relevé le 16/11/2026 pour l'API directe d'Anthropic :

Point d'accès Taille maximale
API Messages 128 Mo
Comptage de jetons 128 Mo
API de lots (Batch) 256 Mo
API de fichiers 500 Mo

Au-delà, l'API répond 413. La page précise que, sur l'API d'Anthropic, c'est Cloudflare qui renvoie cette erreur avant que la requête atteigne les serveurs de l'API.

La forme de l'erreur et le request-id

Le format d’erreur documenté est un JSON avec un objet error contenant un type et un message, plus un champ request_id. Chaque réponse porte aussi un en-tête request-id (de la forme req_…). Gardez-le dans vos journaux : c'est l'identifiant à donner au support. Les SDK Python et TypeScript l'exposent comme propriété _request_id. La documentation précise que les valeurs de ces objets peuvent s'enrichir : de nouveaux types d'erreur peuvent apparaître, donc ne vous appuyez pas sur une liste fermée.

Avec les SDK officiels, les erreurs prennent généralement la forme d’exceptions typées : utilisez leurs classes et le statut plutôt qu’une comparaison fragile du texte du message. Prévoyez aussi le cas d’une connexion échouée sans réponse HTTP, ou d’un intermédiaire qui renvoie un format différent. L’absence d’identifiant de requête ne doit pas faire échouer votre propre journalisation.

Délais et requêtes longues

La page recommande le streaming ou l'API de lots pour les requêtes longues, surtout au-delà de 10 minutes, et déconseille un max_tokens élevé sans l'un des deux : certains réseaux coupent les connexions inactives après une durée variable. Le SDK vérifie que la durée attendue des requêtes non diffusées ne dépasse pas dix minutes ; ce contrôle n’est pas une garantie sur le réseau ni sur le temps réel. Voir le streaming et le traitement par lots.

Erreurs en cours de flux

Avec le streaming, une erreur peut survenir après une réponse 200. La gestion n'est alors pas celle des codes ci-dessus : la page renvoie à la section « Error events » du streaming. Autre confusion fréquente : une réponse limitée par le modèle peut porter une raison d’arrêt dans une réponse HTTP réussie. Une coupure réseau, elle, peut interrompre le flux avant son statut final. Pour suivre les erreurs en production, une page voisine traite du compteur de jetons et des erreurs.

Préparer un diagnostic transmissible

Pour un incident, relevez l’heure, le point d’accès, le code HTTP, le type d’erreur et l’identifiant de requête quand il est disponible. Ajoutez la version du SDK et indiquez si l’appel était diffusé en continu. Un exemple de requête réduit, avec des données fictives, aide à reproduire le problème sans transmettre les documents d’origine.

Évitez d’empiler des reprises automatiques dans plusieurs couches. Si le SDK réessaie déjà, une boucle supplémentaire dans votre application peut multiplier les appels et allonger l’attente. Fixez un nombre total d’essais et un délai acceptable pour l’utilisateur. Un échec persistant doit aboutir à une réponse explicite, plutôt qu’à un écran qui attend indéfiniment.

Questions fréquentes

Que signifie l'erreur 529 de l'API Claude ?

Le type overloaded_error : l'API est temporairement surchargée. La documentation précise qu'elle peut survenir en cas de forte affluence sur l'ensemble des utilisateurs, indépendamment de votre quota.

Quelle est la taille maximale d'une requête à l'API Claude ?

Relevé le 16/11/2026 : 128 Mo pour l'API Messages, 128 Mo pour le comptage de jetons, 256 Mo pour l'API de lots, 500 Mo pour l'API de fichiers. Au-delà : erreur 413.

Le SDK réessaie-t-il tout seul en cas d'erreur ?

Oui. Le SDK officiel réessaie les échecs transitoires (connexion, limites de débit, erreurs 5xx) avec attente exponentielle, deux fois par défaut, en respectant l'en-tête retry-after quand il existe. Le nombre est réglable avec max_retries.

Sources

Pages consultées pour écrire cet article :

  1. https://alma.iarche.fr/fr/api-docs
  2. https://platform.claude.com/docs/en/api/errors

À lire aussi