Guide
Tokens et erreurs d'API : ce qu'il faut suivre
Compter les tokens d'une requête, lire les codes d'erreur 429 et 529 et les limites de débit, d'après la documentation d'Anthropic et d'OpenAI.
Mis à jour le
Une IA en production se mesure d'abord en tokens et en erreurs. Les tokens déterminent le coût et la taille des réponses ; les erreurs disent si l'application arrive encore à parler au modèle. Ce guide décrit ce que les API renvoient pour les compter, et les erreurs à surveiller, d'après la documentation officielle d'Anthropic et d'OpenAI lue le 15/11/2026.
Où se trouve le comptage
Chez Anthropic, deux endroits donnent des tokens. Le premier est le point de comptage (count_tokens), qui accepte les mêmes entrées qu'une création de message : messages, prompt système, outils, images et PDF. Sa réponse contient le nombre de tokens d'entrée, sous le champ input_tokens. L'exemple de la documentation renvoie { "input_tokens": 14 } pour une question de quelques mots. Le second est la réponse d'une création de message : elle contient un objet usage qui indique les tokens consommés par l'appel.
La documentation précise trois points qui évitent les erreurs de lecture :
- le comptage est une estimation, qui peut différer d'un petit nombre de tokens de la consommation réelle ;
- certains tokens ajoutés automatiquement par Anthropic pour l'optimisation du système peuvent figurer dans le comptage, mais ne sont pas facturés ;
- les modèles Claude 4.7 et ultérieurs utilisent un tokenizer qui produit environ 30 % de tokens en plus pour un même texte. Il faut recompter ses prompts avec le modèle visé, et ne pas réutiliser des comptages faits sur un modèle antérieur pour estimer un coût.
Le comptage de tokens est gratuit, mais limité en nombre de requêtes par minute. Selon le palier d'usage, la limite va de 5 000 à 20 000 requêtes par minute dans le tableau de la page. Ces limites sont distinctes de celles de la création de messages.
Ce qu'il faut enregistrer à chaque appel
Pour suivre une dépense, gardez pour chaque appel :
- le nom exact du modèle utilisé, pas seulement sa famille ;
- les tokens d'entrée et de sortie tels que renvoyés par l'API ;
- le coût calculé à partir de ces tokens et du tarif du jour ;
- l'identifiant de requête, qui sert au support en cas de problème.
Ce dernier point est important. Anthropic indique que chaque réponse de l'API contient un en-tête request-id, repris dans le corps des erreurs sous le champ request_id. Un journal sans cet identifiant rend le diagnostic d'un incident beaucoup plus lent. La page sur le journal d'incident détaille cette méthode.
Les erreurs à surveiller
La documentation d'erreurs d'Anthropic classe les réponses par code HTTP. Celles qui comptent en production sont les suivantes :
| Code | Type | Ce que la documentation indique |
|---|---|---|
| 400 | invalid_request_error |
Problème de format ou de contenu de la requête. Renvoyé aussi quand la limite de dépense fixée par l'organisation est atteinte. |
| 401 | authentication_error |
Clé d'API invalide, révoquée ou expirée. |
| 402 | billing_error |
Problème de facturation ou de moyen de paiement. |
| 413 | request_too_large |
Requête au-delà de la taille maximale. |
| 429 | rate_limit_error |
Limite de débit atteinte, ou plafond mensuel de dépense du palier atteint. |
| 500 | api_error |
Erreur interne, à retenter avec un délai croissant. |
| 504 | timeout_error |
Délai dépassé pendant le traitement. |
| 529 | overloaded_error |
API temporairement surchargée. |
Deux nuances méritent un suivi séparé. Une erreur 429 avec un plafond mensuel atteint ne comporte pas d'en-tête retry-after et ne se résout pas en attendant : elle demande une action sur la facturation. Une erreur 400 liée à la limite de dépense ressemble à une erreur de requête alors qu'elle vient d'un réglage de budget. Les deux doivent être séparées dans vos alertes.
Le SDK officiel d'Anthropic réessaie automatiquement les erreurs transitoires, deux fois par défaut, en respectant l'en-tête retry-after. Un suivi doit compter ces nouvelles tentatives, sinon il sous-estime le nombre réel d'appels.
Les limites de débit chez OpenAI
La page de limites de débit d'OpenAI mesure le trafic en plusieurs unités : requêtes par minute (RPM), requêtes par jour (RPD), tokens par minute (TPM), tokens par jour (TPD) et images par minute. La première limite atteinte bloque les requêtes, même si les autres ne le sont pas. Vingt petites requêtes peuvent ainsi saturer une limite de 20 RPM sans approcher la limite de TPM.
La page cite des en-têtes de réponse qui donnent l'état des limites, dont x-ratelimit-limit-requests, x-ratelimit-remaining-requests, x-ratelimit-reset-requests, ainsi que leurs équivalents pour les tokens. Elle décrit Retry-After, qui donne le délai minimal avant une nouvelle tentative lorsque la réponse est une 429 ou une 503 temporaire.
Les requêtes échouées comptent aussi dans la limite par minute. Un programme qui réessaie sans délai peut donc aggraver la situation qu'il tente de corriger.
Quoi tracer, concrètement
- le nombre de réponses 429 et 529 par heure, séparé par modèle ;
- les tokens d'entrée et de sortie moyens par type de requête, pour repérer une réponse qui s'allonge ;
- le taux de nouvelles tentatives, qui montre une API saturée avant qu'elle ne tombe ;
- les 401 et 402, qui signalent un problème de clé ou de facturation et non de trafic.
Pour les seuils et les alertes, voir six signaux à surveiller. Pour la maîtrise des dépenses, voir aussi calculer le coût d'un appel API d'IA.
Questions fréquentes
Le comptage avant l'appel coûte-t-il quelque chose ?
Selon la documentation d'Anthropic, le comptage de tokens est gratuit, mais il est soumis à des limites de requêtes par minute, distinctes de celles de la création de messages.
Faut-il réessayer une erreur 429 immédiatement ?
Non. OpenAI recommande un backoff exponentiel avec jitter, un nombre de tentatives limité, et de ne pas réessayer les erreurs liées au quota ou à la facturation. Lorsque l'en-tête Retry-After est présent, il indique le délai minimal à attendre.
Sources
Pages consultées pour écrire cet article :