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
Originque 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 :