Erreur 429 rate_limit_error dans l’API Claude — signification et résolution

429 signifie « ralentissez », pas « vous n’avez plus d’argent ». La différence compte : pour l’un, il faut attendre ; pour l’autre, recharger — et les confondre entraîne des heures de débogage au mauvais endroit.

L’erreur

resposta (HTTP 429)

{
  "type": "error",
  "error": { "type": "rate_limit_error",
             "message": "Number of requests has exceeded your rate limit" }
}

Causes et solutions en bref

Cause	Solution
Nombre de requêtes par minute supérieur à la limite de votre compte	Mettez les requêtes en file et limitez la concurrence côté client au lieu de tout envoyer en une fois.
Nombre de tokens par minute supérieur à la limite	Les prompts longs consomment le quota de tokens bien avant le quota de requêtes. Réduisez le contexte ou divisez le travail.
Plusieurs processus utilisent la même clé	La limite s’applique à la clé, pas au processus. Les workers parallèles s’additionnent au regard du même quota.
Nouvelle tentative sans backoff	Répéter immédiatement vous maintient en permanence au-dessus de la limite. Un backoff exponentiel avec jitter est obligatoire.

Respectez retry-after lorsqu’il est fourni

Lorsque la réponse contient l’en-tête retry-after, ce n’est pas une suggestion : c’est la durée exacte au terme de laquelle la requête sera de nouveau acceptée. Attendre moins garantit un autre 429.

retry_after.py

import time
from openai import APIStatusError

try:
    resp = client.chat.completions.create(model=MODELO, messages=msgs)
except APIStatusError as e:
    if e.status_code == 429:
        espera = float(e.response.headers.get("retry-after", 5))
        time.sleep(espera)
        resp = client.chat.completions.create(model=MODELO, messages=msgs)
    else:
        raise

Limitez la concurrence à la source

La cause la plus fréquente n’est pas le volume total, mais la rafale : vingt requêtes lancées au même instant dépassent une limite que soixante requêtes réparties sur une minute ne dépasseraient pas. Un sémaphore résout ce que le retry seul ne résout pas.

concorrencia.py

import asyncio

LIMITE = asyncio.Semaphore(4)   # no máximo 4 chamadas simultâneas

async def chamar(msgs):
    async with LIMITE:
        return await client.chat.completions.create(
            model=MODELO, messages=msgs)

Confirmez qu’il s’agit d’une limite, et non d’un solde

Un 429 ne signifie jamais un manque de crédits — cela correspond à 402. Si vos journaux mélangent les deux, séparez-les par statut avant d’enquêter : le correctif du 429 est la temporisation ; celui du 402 est le rechargement. Répéter un 402 échoue indéfiniment.

Si vous appelez via Kunavo

Chez Kunavo, les limites s’appliquent à la clé et le solde est un portefeuille prépayé séparé ; les deux cas ont donc des statuts différents : 429 pour une limite de débit et 402 lorsque le solde ne couvre pas l’appel — jamais l’un déguisé en l’autre. Les requêtes refusées ne sont pas facturées. Les tarifs par token, qui déterminent la quantité de solde consommée par chaque appel, sont indiqués dans notre guide des tarifs de l’API Claude.

Questions fréquentes

429 signifie-t-il que mes crédits sont épuisés ?

Non. Un solde insuffisant correspond à 402. Le 429 concerne la vitesse : vous avez envoyé trop de requêtes ou de tokens en trop peu de temps, et attendre suffit.

Combien de temps dois-je attendre ?

Si l’en-tête retry-after est présent, exactement cette durée. Sinon, appliquez un backoff exponentiel à partir de 1–2 secondes avec jitter, jusqu’à un plafond de 30–60 secondes.

Augmenter la limite résout-il le problème ?

Cela aide si le volume est réellement élevé, mais la plupart des 429 proviennent de courtes rafales. Limiter la concurrence suffit généralement sans modifier aucune limite.

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.