Erreur API 429 Too Many Requests : limites, Retry-After et backoff sécurisé

Pourquoi le code HTTP 429 apparaît : anatomie des limites

Dans les API de modèles de langage modernes (OpenAI, Anthropic et passerelles compatibles), le code 429 est déclenché par trois mécanismes distincts :

1. RPM (Requests Per Minute) : limite sur le nombre de requêtes HTTP par minute. Se produit lors de l'exécution de multiples processus parallèles sans file d'attente.
2. TPM (Tokens Per Minute) : limite sur le volume cumulé de tokens d'entrée et de sortie sur une fenêtre glissante d'une minute. Très fréquent lors de l'envoi de contextes volumineux.
3. Épuisement du quota ou du solde : blocage dû à un solde nul, à un plafond de dépenses atteint ou à l'expiration d'un forfait prépayé.

HTTP/1.1 429 Too Many Requests
Date: Sun, 23 Aug 2026 03:00:00 GMT
Content-Type: application/json
Retry-After: 6
x-ratelimit-limit-requests: 500
x-ratelimit-remaining-requests: 0
x-ratelimit-reset-requests: 6s
x-ratelimit-limit-tokens: 30000
x-ratelimit-remaining-tokens: 1200
x-ratelimit-reset-tokens: 150ms

{
  "error": {
    "message": "Rate limit reached for model in organization on tokens per minute (TPM). Please try again in 6s.",
    "type": "tokens",
    "param": null,
    "code": "rate_limit_exceeded"
  }
}

Lorsque l'erreur provient d'un solde insuffisant ou de restrictions rigides d'abonnement, les nouvelles tentatives automatiques gaspillent inutilement les ressources réseau. Pour isoler immédiatement la cause sans analyser des journaux complexes, BetterToken met à disposition un tableau de bord complet : il affiche en temps réel les statuts HTTP de chaque requête, la répartition exacte des tokens d'entrée, de sortie et de cache, ainsi que le solde selon le modèle pay-as-you-go sans interruption de 5 heures.

Matrice de diagnostic de l'erreur 429

Comment analyser l'en-tête Retry-After

La spécification RFC 6585 prévoit deux formats valides pour l'en-tête Retry-After :

• Secondes relatives (nombre entier ou décimal, par exemple Retry-After: 12) ;
• Date HTTP (horodatage GMT standardisé, par exemple Retry-After: Sun, 23 Aug 2026 03:05:00 GMT).

import datetime
import email.utils
import time

def parse_retry_after(header_value: str | None, default_delay: float = 1.0) -> float:
    if not header_value:
        return default_delay
    header_value = header_value.strip()
    try:
        return max(0.0, float(header_value))
    except ValueError:
        pass

    try:
        parsed_date = email.utils.parsedate_to_datetime(header_value)
        now = datetime.datetime.now(datetime.timezone.utc)
        delay = (parsed_date - now).total_seconds()
        return max(0.0, delay)
    except Exception:
        return default_delay

Implémentation du Full Jitter Exponential Backoff

En l'absence d'en-tête Retry-After, la méthode standard est le recul exponentiel avec variation aléatoire totale (Full Jitter). La formule de calcul pour la tentative $i$ est :

$T_{ ext{wait}} = ext{random}(0, \min(T_{ ext{max}}, T_{ ext{base}} imes 2^i))$

import asyncio
import json
import random
import httpx

class RateLimitRetryClient:
    def __init__(
        self,
        base_url: str = "https://www.bettertoken.ai/v1",
        api_key: str = "",
        max_retries: int = 4,
        base_delay: float = 1.0,
        max_delay: float = 32.0,
    ):
        self.base_url = base_url
        self.api_key = api_key
        self.max_retries = max_retries
        self.base_delay = base_delay
        self.max_delay = max_delay
        self.client = httpx.AsyncClient(
            base_url=self.base_url,
            headers={"Authorization": f"Bearer {self.api_key}"},
            timeout=60.0,
        )

    async def send_chat_completion(self, payload: dict) -> dict:
        for attempt in range(self.max_retries + 1):
            try:
                response = await self.client.post("/chat/completions", json=payload)
                if response.status_code == 200:
                    return response.json()

                if response.status_code == 429:
                    error_data = response.json().get("error", {})
                    error_code = error_data.get("code")

                    if error_code in ("insufficient_quota", "billing_not_active"):
                        raise RuntimeError(f"Erreur de facturation : {error_data.get('message')}")

                    if attempt == self.max_retries:
                        raise RuntimeError(f"Nombre maximal de tentatives atteint (429) : {response.text}")

                    retry_after = response.headers.get("Retry-After")
                    if retry_after:
                        wait_time = parse_retry_after(retry_after) + random.uniform(0.1, 0.5)
                    else:
                        backoff_cap = min(self.max_delay, self.base_delay * (2 ** attempt))
                        wait_time = random.uniform(0, backoff_cap)

                    await asyncio.sleep(wait_time)
                    continue

                response.raise_for_status()

            except httpx.RequestError as exc:
                if attempt == self.max_retries:
                    raise
                wait_time = min(self.max_delay, self.base_delay * (2 ** attempt))
                await asyncio.sleep(wait_time)

        raise RuntimeError("La requête a échoué après épuisement du budget de tentatives")
Afficher plus

Idempotence et sécurité des opérations

Répéter des opérations de lecture (GET) est intrinsèquement sûr. En revanche, lors de l'exécution d'inférences LLM via POST :

1. Évitez de dupliquer les tâches d'agents : si une requête est interrompue par un timeout, vérifiez si des tokens ont été consommés avant de la relancer.
2. Utilisez des identifiants uniques de requête : transmettez un en-tête X-Request-ID pour suivre les appels dans les journaux.
3. Ne traitez pas les erreurs 401 ou 403 comme du 429 : les erreurs d'authentification nécessitent la mise à jour des clés d'accès et non une simple pause.

Vérification et reprise de service

Avant de rétablir le trafic complet :

• Envoyez une requête de test minimale (max_tokens: 5).
• Vérifiez la réception d'un code HTTP 200 et inspectez l'en-tête x-ratelimit-remaining-requests.
• Augmentez progressivement la charge tout en surveillant le ratio d'erreurs 429 dans vos outils d'analyse.

Pour éliminer les blocages 429 soudains liés à des limites strictes par minute et garder une visibilité totale sur chaque appel, passez à BetterToken API, créez des clés d'accès dédiées et suivez votre consommation de tokens en direct dans le tableau de bord.

Sources et références

• RFC 6585: Additional HTTP Status Codes (429 Too Many Requests)
• OpenAI Guide on Rate Limits & Error Handling
• BetterToken API Reference & Documentation