Claude API 429 rate_limit_error — causes et solution durable

Un 429 de l’API Claude signifie que vous avez dépassé l’une des limites par minute d’Anthropic — requêtes, tokens d’entrée ou tokens de sortie. La solution consiste rarement à « attendre plus longtemps » : il faut respecter retry-after, ajouter un backoff avec jitter et lisser les pics. Voici la procédure complète.

L’erreur

response (HTTP 429)

{
  "type": "error",
  "error": {
    "type": "rate_limit_error",
    "message": "Number of request tokens has exceeded your per-minute rate limit"
  }
}

Causes et solutions en bref

Cause	Solution
Limite de requêtes par minute (RPM) atteinte	Mettez les requêtes en file côté client ; respectez l’en-tête retry-after avant de réessayer.
Limite de tokens d’entrée par minute (ITPM) atteinte — prompts volumineux, peu de requêtes	Réduisez le contexte récupéré et activez la mise en cache des prompts afin que les tokens mis en cache cessent d’être comptabilisés dans les offres prises en charge.
Limite de tokens de sortie par minute (OTPM) atteinte	Définissez max_tokens de manière réaliste — l’OTPM est souvent le premier plafond pour les longues générations.
Trafic en rafale (le cron lance tout à :00)	Ajoutez du jitter aux planifications et répartissez les tâches par lots sur toute la minute.

Lisez la réponse avant de réessayer

Anthropic renvoie un en-tête retry-after indiquant le nombre de secondes à attendre, et le message d’erreur précise la limite franchie. Réessayer instantanément sans le lire est la manière de transformer un seul 429 en tempête de 429.

Ajoutez un backoff exponentiel avec jitter

Ne réessayez que les statuts réessayables (429, 500, 529), jamais les erreurs d’authentification ou de validation. Cet extrait fonctionne tel quel directement avec Anthropic ou avec tout endpoint compatible OpenAI :

backoff.py

import time, random
from openai import OpenAI, APIStatusError

client = OpenAI(base_url="https://api.kunavo.com/v1", api_key="sk-kn-...")

def with_backoff(fn, max_retries=5):
    for attempt in range(max_retries):
        try:
            return fn()
        except APIStatusError as e:
            if e.status_code not in (429, 500, 529):
                raise                      # don't retry auth/validation errors
            retry_after = e.response.headers.get("retry-after")
            delay = float(retry_after) if retry_after else min(2 ** attempt, 30)
            time.sleep(delay + random.uniform(0, 0.5))   # jitter avoids herds
    raise RuntimeError("retries exhausted")

resp = with_backoff(lambda: client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[{"role": "user", "content": "ping"}],
    max_tokens=32,
))
print(resp.choices[0].message.content)

Réduisez les tokens, pas seulement les requêtes

Si le message mentionne les limites de tokens, le backoff seul ne suffira pas. Réduisez les fragments récupérés, plafonnez max_tokens et activez la mise en cache des prompts — un grand prompt système stable facturé à 10 % du tarif des tokens d’entrée soulage également la pression sur l’ITPM.

Si vous appelez via Kunavo

Appeler Claude via Kunavo ne supprime pas magiquement les limites de débit, mais modifie l’économie des erreurs : les requêtes échouées (y compris les 429) ne sont jamais facturées, et le tableau de bord d’utilisation par clé indique précisément quelle clé et quel modèle produisent la rafale afin que vous puissiez la lisser. Le même extrait de backoff ci-dessus fonctionne tel quel ; seule la base_url change. Les limites de débit sont un plafond de débit, pas un prix — pour connaître le coût réel d’un appel Claude par million de tokens, avec le tarif officiel d’Anthropic à côté du nôtre, consultez la grille tarifaire de l’API Anthropic Claude.

Questions fréquentes

Le passage à un niveau Anthropic supérieur supprime-t-il les 429 ?

Les niveaux supérieurs augmentent les plafonds par minute, ce qui rend les 429 plus rares, mais tout plafond fixe peut être atteint par une rafale. Le code de production doit donc prévoir un backoff quel que soit le niveau.

Dois-je réessayer immédiatement après un 429 ?

Non — respectez l’en-tête retry-after, ou utilisez un backoff exponentiel avec jitter s’il est absent. Les retries immédiats prolongent la fenêtre limitée et peuvent entraîner un blocage plus long.

Les requêtes 429 échouées coûtent-elles de l’argent ?

Anthropic ne facture pas les requêtes rejetées, et Kunavo non plus : les requêtes échouées ne sont jamais facturées. Le coût d’un 429 est de la latence, pas de l’argent.

Guides associés

La sémantique détaillée des erreurs est disponible dans référence des erreurs ; obtenir une clé prend une minute via inscription et la guide d’authentification.