Limites de débit dans Claude Code : distinguer l’abonnement des 429 d’API

Ce qu’une limite de débit signifie dans Claude Code

Claude Code prend en charge deux modes d’authentification fondamentalement différents :

• Abonnement (Pro, Max, Team ou Enterprise) : connexion via OAuth Claude.ai. Claude Code et les autres surfaces Claude puisent dans le pool partagé du plan ; consultez les fenêtres en cours et les restrictions supplémentaires dans /usage et les paramètres du compte.
• Clé d’API (ANTHROPIC_API_KEY dans l’environnement) : les requêtes vont directement vers api.anthropic.com. Les limites sont les RPM, ITPM et OTPM correspondant au niveau de votre espace de travail dans Anthropic Console.

Si ANTHROPIC_API_KEY est défini, il est prioritaire sur l’abonnement. Claude Code bascule vers cette clé même si vous êtes connecté avec un abonnement : c’est une source fréquente de confusion.

Vous devez savoir si la requête a atteint un endpoint tiers ? BetterToken ajoute une couche de diagnostic : son Dashboard affiche le statut de la requête, le modèle, les tokens d’entrée, de sortie et de cache, ainsi que le débit correspondant. Cela aide à distinguer une limite de fournisseur d’une erreur de l’API Anthropic. Consultez la documentation BetterToken pour configurer la Base URL et la clé d’API, puis vérifiez la configuration au regard de votre workflow actuel.

Identifier une limite d’abonnement, d’API Anthropic ou d’un autre endpoint

Commencez par exécuter /status dans Claude Code. La commande indique la méthode d’authentification active : compte avec abonnement ou clé d’API. C’est elle qui détermine la suite du diagnostic.

• Abonnement Pro/Max/Team : /status indique un abonnement et le message mentionne une limite de session ou hebdomadaire avec une heure de réinitialisation. L’usage du plan est épuisé : attendez la réinitialisation et vérifiez /usage, puis /usage-credits s’il est disponible.
• API Anthropic 429 : /status indique une clé d’API, ANTHROPIC_API_KEY existe dans l’environnement et la réponse contient HTTP 429 ou rate_limit_error. Les RPM, ITPM ou OTPM du niveau sélectionné sont contraints. Vérifiez d’abord retry-after, puis réduisez le parallélisme.
• Endpoint tiers : une Base URL personnalisée et une clé de fournisseur sont utilisées ; le code et le format de réponse peuvent différer de ceux d’Anthropic. Lisez d’abord la réponse, puis consultez la page de statut et les conditions de quota du fournisseur.

Traitez séparément 500 api_error, 504 timeout_error et 529 overloaded_error. Ce sont des erreurs serveur ou transitoires, pas la preuve qu’une allocation d’abonnement est épuisée. Utilisez un backoff exponentiel borné. Chaque réponse Anthropic contient request-id dans un en-tête, et une erreur inclut aussi request_id dans le JSON ; conservez cet identifiant pour le support.

Diagnostic pas à pas sans exposer une clé d’API

Étape 1. Vérifier la méthode d’authentification

Dans une session Claude Code :

/status

Regardez « Login method » ou « Auth token ». Si ANTHROPIC_API_KEY est défini mais que vous voulez utiliser un abonnement, supprimez d’abord la variable :

unset ANTHROPIC_API_KEY

Redémarrez Claude Code puis vérifiez de nouveau /status.

Étape 2. Lire le message d’erreur complet

Le texte exact est le principal signal : « Resets at [heure] » indique une limite d’abonnement ; rate_limit_error avec retry-after indique une API 429 à examiner dans Anthropic Console ; api_error, timeout_error et overloaded_error sont des erreurs 5xx/529 transitoires à réessayer avec un backoff ; un format de fournisseur avec une Base URL non standard indique un problème côté fournisseur.

Conservez un ensemble de diagnostic sûr : heure, error.type, request-id/request_id, version de Claude Code et endpoint sélectionné. N’incluez ni clé d’API, ni en-tête Authorization, ni contenu de .env.

Étape 3. Vérifier l’usage actuel

Pour un abonnement :

/usage

Cette commande affiche les barres d’usage Pro/Max : ce qu’il reste avant la réinitialisation de la fenêtre de cinq heures et avant le plafond hebdomadaire. Changer de modèle avec /model ne restaure pas les heures de calcul déjà consommées ; l’allocation est partagée entre les modèles.

Pour l’API, ouvrez Anthropic Console → Settings → Limits. Vous y verrez le niveau, les limites RPM/ITPM/OTPM actuelles et l’usage. Pour BetterToken, ouvrez le Dashboard et retrouvez la requête par son heure : vous pouvez vérifier modèle, statut, tokens d’entrée, de sortie et de cache, ainsi que le débit. Il établit si la requête a atteint BetterToken, mais conservez séparément l’identifiant du corps de réponse ou des en-têtes.

Étape 4. Vérifier le statut officiel

https://status.anthropic.com/

Un incident affectant Claude Code ou l’API explique le problème indépendamment de vos limites.

Étape 5. Rechercher des conflits de configuration

Définir à la fois ANTHROPIC_API_KEY et ANTHROPIC_BASE_URL peut entraîner un comportement inattendu. Ne conservez pas deux jeux de variables pour des schémas d’authentification différents dans le même environnement. Pour demander de l’aide, ne mettez jamais Authorization, x-api-key ou .env dans des journaux ou captures ; le texte d’erreur, le code HTTP, claude --version et /status sans valeurs de clés suffisent.

Que faire après avoir identifié l’origine

Limite d’abonnement (Pro/Max/Team) : attendez la réinitialisation indiquée par /usage et le message d’erreur. Si la limite concerne un modèle, choisissez un modèle disponible avec /model ; cela ne réinitialise pas l’usage global. Exécutez /usage-credits si des crédits sont disponibles, et utilisez /clear entre des tâches sans rapport pour réinitialiser le contexte et limiter les requêtes suivantes.

API Anthropic 429 (rate_limit_error) : lisez retry-after et attendez la durée indiquée ; réduisez le parallélisme, car les tâches d’agents parallèles consomment plus vite RPM, ITPM et OTPM. Vérifiez le niveau actuel dans Anthropic Console → Settings → Limits plutôt que d’anciens chiffres fixes. Pour un besoin durablement supérieur, demandez une hausse des limites à Anthropic via la Console.

Endpoint tiers : ouvrez la page de statut, demandez au fournisseur son quota actuel et son format d’erreur, puis basculez si nécessaire vers l’API Anthropic directe ou un autre fournisseur.

5xx / 529 : appliquez un backoff exponentiel borné pour 500, 504 et 529 ; le SDK officiel réessaie déjà certaines erreurs transitoires. Vérifiez status.anthropic.com et, si l’erreur persiste, transmettez au support le request-id, l’heure et le type d’erreur, sans secrets.

Quand attendre, modifier la charge ou contacter le support ?

• Limite d’abonnement avec heure de réinitialisation : attendre, changer de modèle ou utiliser /clear.
• API 429 avec retry-after : attendre la durée indiquée et réduire le parallélisme.
• API 429 fréquentes sans retry-after : vérifier le niveau et demander une limite supérieure si nécessaire.
• 500 / 504 / 529 : appliquer un backoff exponentiel borné, vérifier le statut du service et conserver le request-id.
• Erreur d’endpoint tiers : contacter ce fournisseur.
• Limite inexpliquée avec un abonnement actif : contacter le support Claude.ai.
• Limite inexpliquée avec une clé d’API active : contacter le support Anthropic Console.

Le support des abonnements et celui de l’API sont deux équipes distinctes. L’équipe Anthropic API Console ne peut pas résoudre une limite d’abonnement Pro/Max, et inversement.

FAQ

Pourquoi vois-je « rate limit » dès le début d’une session ?

Les causes possibles sont les suivantes : (1) l’environnement contient un ANTHROPIC_API_KEY associé à un niveau bas, prioritaire sur l’abonnement ; vérifiez avec /status. (2) Une session précédente a consommé une large part de la fenêtre glissante, qui ne se réinitialise pas au redémarrage de Claude Code. (3) Plusieurs appareils ou tâches d’agents utilisent le même compte ; leurs usages sont cumulés.

Changer de modèle avec /model peut-il aider ?

Partiellement pour les abonnements. « You've hit your Opus limit » signifie que l’allocation Opus est épuisée ; passer à Sonnet peut permettre de continuer dans la même session. Le budget de calcul partagé sur cinq heures et sur la semaine n’est toutefois pas restauré par le changement de modèle.

Dois-je joindre les journaux complets lorsque je demande de l’aide ?

Non. Le texte d’erreur complet, le code HTTP, la sortie de /status sans valeurs de clés, claude --version, l’heure et l’état de status.anthropic.com à ce moment-là suffisent.

Quelles limites dynamiques changent le plus souvent ?

Les limites API par niveau (RPM, ITPM et OTPM) et les paramètres des fenêtres d’abonnement peuvent évoluer. Obtenez les valeurs actuelles uniquement depuis les pages officielles :

• Coûts et usage : code.claude.com/docs/en/costs
• Erreurs et limites de débit de l’API : platform.claude.com/docs/en/api/errors
• État du service : status.anthropic.com

Ne vous fiez pas aux chiffres trouvés dans des tutoriels ou forums : ils deviennent vite obsolètes.