BroadRouter

Gérer les erreurs 429 d’une API LLM : backoff, jitter et limiteurs

Par l’équipe BroadNet Inference · 5 min de lecture · Publié · Mis à jour

Une erreur 429 signifie que vous avez atteint une limite de débit, de simultanéité ou de dépense. Relancez avec un backoff exponentiel plafonné et un jitter aléatoire, et respectez Retry-After s’il est envoyé. Évitez ensuite la plupart des 429 : plafonnez les requêtes en cours avec un sémaphore réglé sur la limite de la clé et mettez le reste en file d’attente. Relancez les 5xx de la même façon ; corrigez les autres 4xx.

Une erreur 429 signifie que votre trafic a dépassé une limite de débit : requêtes par minute, requêtes en cours, tokens par minute ou dépense. La correction se fait en deux moitiés. Bien relancer : un backoff exponentiel plafonné avec un jitter aléatoire, en respectant Retry-After. Envoyer moins à la fois : un sémaphore réglé sur la limite de requêtes en cours de la clé, plus une file d’attente. Les deux sont ci-dessous, avec du code.

Pour la référence complète des codes de statut, voir le guide des erreurs et des retries ; pour les exécutions d’agents de plusieurs heures avec points de reprise et délais d’expiration, voir agents de longue durée : délais et retries.

Quelle est la différence entre 429 et 5xx ?

Statut À qui le problème Relancer ? Comment
429 Votre trafic a dépassé une limite Oui Backoff avec jitter ; respecter Retry-After ; réduire la simultanéité
500 / 502 / 503 / 504 Côté serveur Oui Backoff exponentiel borné
Connexion réinitialisée, délai dépassé Réseau ou serveur En général Backoff ; pour les flux, seulement si une nouvelle facturation est acceptable
400 / 422 Requête invalide Non Corriger la charge utile
401 / 402 / 403 Clé, solde ou politique Non Corriger la clé, approvisionner le compte, corriger la liste d’autorisation
413 Requête trop volumineuse Non La réduire

Chez BroadNet Inference, une 429 peut correspondre à l’une de quatre limites : débit, simultanéité, débit de tokens ou dépense. Une limite de dépense ne se lèvera pas en 30 secondes. La documentation de BroadNet ne dit pas quel champ du corps de l’erreur nomme la limite : journalisez le corps et comparez-le avec les limites affichées dans les détails de votre clé.

Notre jeu de données ouvert sur les offres gratuites et limites de débit des API LLM compare ce que 14 fournisseurs publient sur l’accès gratuit, les limites de débit de départ, l’exigence d’une carte bancaire et l’entraînement sur les données des offres gratuites, avec la source et la date de chaque valeur.

Quelles limites provoquent des 429 ?

Connaissez les chiffres avec lesquels vous travaillez. Chez BroadNet Inference :

Type de clé Requêtes / minute En cours Autre
Paiement à l’usage 30 4 Budget de dépense partagé
Clé horaire 120 1 flux 300,000 tokens / minute
Session de forfait illimité — 1 requête par session Pas de compteur de tokens

Pour les LLM, c’est le nombre de requêtes en cours qui compte le plus. Une réponse en streaming garde son emplacement jusqu’à l’arrivée du dernier token : une longue réponse l’occupe donc aussi longtemps que le modèle met à l’écrire (BroadNet indique une vitesse typique de environ 100 tokens par seconde). Envoyez plus d’appels parallèles que les 4 emplacements de la clé et les appels en trop recevront une 429, alors que vous n’avez envoyé qu’une poignée de requêtes dans la minute. C’est un problème de simultanéité, et le backoff seul le gère mal. Pour dimensionner vos workers face à une limite avant le lancement, utilisez le calculateur gratuit de limites de débit LLM. Pour un traitement fixe de nombreux éléments, le planificateur de traitements par lots LLM convertit les mêmes limites en durée d’exécution. D’autres fournisseurs comptent autrement (tokens par minute, requêtes par jour ou requêtes en cours) ; les limites de débit des API LLM par fournisseur en compare 13 d’après leur propre documentation.

Comment écrire un backoff avec jitter ?

Un backoff exponentiel simple attend 1, 2, 4, 8 secondes. Si cent workers ont été limités au même moment, ils reviennent tous au même moment. La simulation d’AWS avec 100 clients en concurrence a montré que le full jitter réduisait le nombre d’appels de plus de moitié et terminait plus tôt qu’un backoff sans jitter. La version la plus simple, le full jitter, attend un temps aléatoire entre zéro et le plafond exponentiel :

import os, random, time
from openai import OpenAI, RateLimitError, APIStatusError, APIConnectionError

client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"], max_retries=0)

RETRYABLE = {429, 500, 502, 503, 504}

def call_with_backoff(max_attempts=6, base=1.0, cap=60.0, **kwargs):
    for attempt in range(max_attempts):
        try:
            return client.chat.completions.create(**kwargs)
        except (RateLimitError, APIStatusError, APIConnectionError) as e:
            status = getattr(e, "status_code", None)
            if status is not None and status not in RETRYABLE:
                raise  # 400, 401, 403...: retrying will not help
            if attempt == max_attempts - 1:
                raise
            retry_after = None
            if getattr(e, "response", None) is not None:
                retry_after = e.response.headers.get("retry-after")
            wait = random.uniform(0, min(cap, base * 2 ** attempt))
            if retry_after and retry_after.isdigit():
                wait = max(wait, float(retry_after))
            time.sleep(wait)

max_retries=0 désactive les retries propres au SDK pour ne pas relancer deux fois. Si le comportement intégré du SDK vous convient, l’inverse fonctionne aussi : supprimez votre boucle et réglez max_retries=4 sur le client, comme le montre le guide du SDK Python. Les SDK officiels Python et Node relancent par défaut deux fois les erreurs de connexion, 408, 409, 429 et 5xx.

Retry-After est un en-tête standard (RFC 9110) qui peut contenir des secondes ou une date. La documentation de BroadNet ne le garantit pas : le code le traite donc comme optionnel.

Comment éviter les 429 avant qu’elles n’arrivent ?

Plafonnez les requêtes en cours à la limite de la clé. En Python, un asyncio.Semaphore le fait avec un seul objet et un seul bloc async with. Le code prend 4 comme exemple ; réglez-le sur la limite de requêtes en cours de votre clé (4 sur une clé BroadNet à l’usage) :

import asyncio, os
from openai import AsyncOpenAI

client = AsyncOpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"], max_retries=4)
slots = asyncio.Semaphore(4)  # match the key's in-flight limit

async def ask(prompt):
    async with slots:
        r = await client.chat.completions.create(
            model="broadnet/gemma-4-26b-a4b",
            messages=[{"role": "user", "content": prompt}],
        )
        return r.choices[0].message.content

async def main(prompts):
    return await asyncio.gather(*(ask(p) for p in prompts))

results = asyncio.run(main(["Summarise A", "Summarise B", "Summarise C"]))

gather lance toutes les tâches, mais seulement autant que le sémaphore l’autorise s’exécutent à la fois. Les autres attendent dans la file du sémaphore. En Node, le paquet p-limit fait la même chose, là encore avec 4 comme valeur d’exemple :

// ES module (top-level await). npm install openai p-limit
import OpenAI from "openai";
import pLimit from "p-limit";

const client = new OpenAI({ baseURL: "https://inference.broadnet.ai/v1", apiKey: process.env.BROADNET_API_KEY, maxRetries: 4 });
const limit = pLimit(4); // match the key's in-flight limit

async function ask(prompt) {
  const r = await client.chat.completions.create({
    model: "broadnet/gemma-4-26b-a4b",
    messages: [{ role: "user", content: prompt }],
  });
  return r.choices[0].message.content;
}

const prompts = ["Summarise A", "Summarise B", "Summarise C"];
const results = await Promise.all(prompts.map((p) => limit(() => ask(p))));

Pour ajouter un plafond par minute, ajoutez un token bucket qui libère une autorisation toutes les 60 / rpm secondes, rpm étant la limite de requêtes par minute de votre clé (30 sur une clé BroadNet à l’usage).

Quand faut-il une vraie file d’attente ?

Un sémaphore vit dans un seul processus. Dès que plusieurs workers ou serveurs partagent une clé, la limite est partagée et chaque processus ne voit que son propre trafic. Dans ce cas :

  1. Placez les tâches dans une file partagée (Redis, SQS, une table de base de données).
  2. Faites tourner un nombre fixe de consommateurs, égal à la limite de requêtes en cours de la clé.
  3. Donnez un identifiant à chaque tâche et stockez les résultats par identifiant, pour qu’une tâche relancée ne s’exécute pas deux fois.
  4. Faites passer le trafic interactif et le trafic par lots par des clés ou des files distinctes, pour qu’un arriéré de lots ne bloque jamais un utilisateur qui attend une réponse.

Pour un traitement en masse de milliers d’éléments sans Batch API, voir l’exécuteur de lots capable de reprendre.

Quelles erreurs de retry transforment des 429 en pannes ?

  • Des retries sans limite. Une boucle de retry sans plafond pendant une longue panne multiplie votre charge et, en facturation au token, votre facture.
  • Relancer à l’aveugle un flux à moitié terminé. Si le flux a déjà renvoyé des tokens, un retry est une nouvelle inférence et l’utilisateur risque de voir le texte deux fois. Voir l’article sur le streaming pour détecter les flux incomplets.
  • Relancer des erreurs de compte. Une 401 pour un quota de paiement à l’usage épuisé ou une 402 pour un solde insuffisant ne se corrigera pas d’elle-même.

Journalisez chaque retry avec son statut, son temps d’attente et l’en-tête de réponse X-Request-ID, que la documentation de BroadNet demande de conserver pour le support. Un taux de retry en hausse est le premier signe qu’il vous faut plus de capacité ; la journalisation de l’usage montre comment l’enregistrer.

La place de BroadNet Inference

Les limites de BroadNet sont publiées et assez basses pour concevoir en conséquence : 4 requêtes en cours sur une clé en paiement à l’usage. Cela convient aux applications et aux agents, et c’est trop juste pour un traitement en masse qui veut des centaines d’appels parallèles sur une seule clé. Pour les agents, un forfait illimité n’a pas de compteur de tokens et traite une requête à la fois par session ; vous ajoutez des sessions pour le travail en parallèle, comme décrit dans faire tourner des agents de code en parallèle. Les limites actuelles figurent dans la référence de l’API.

Questions fréquentes

Que signifie le code HTTP 429 sur une API LLM ?

Too Many Requests (trop de requêtes). Vous avez dépassé une limite de requêtes par minute, de requêtes en cours, de tokens par minute ou de dépense. La requête n’a pas été traitée : vous pouvez donc la renvoyer sans risque après une attente.

Combien de temps attendre avant de relancer après une 429 ?

Utilisez Retry-After si le serveur l’envoie. Sinon, commencez vers une seconde, doublez à chaque tentative, plafonnez autour de 30 à 60 secondes et tirez une attente aléatoire entre zéro et ce plafond. Arrêtez-vous après quatre à six tentatives.

Faut-il relancer les erreurs 500 et 503 d’une API LLM ?

Oui, avec le même backoff borné. Elles viennent du serveur. Une 400, 401, 403 ou 422 échouera de la même façon à chaque fois : corrigez-la plutôt.

Le SDK OpenAI relance-t-il automatiquement les 429 ?

Oui. Les SDK officiels Python et Node relancent par défaut deux fois les erreurs de connexion, 408, 409, 429 et 5xx, avec un court backoff exponentiel. Augmentez max_retries pour les traitements par lots et ajoutez votre propre limite de simultanéité.

Pourquoi ai-je une 429 alors que je suis sous la limite de requêtes par minute ?

En général à cause de la limite de simultanéité. Les longues réponses en streaming restent en cours pendant de nombreuses secondes : quelques appels parallèles suffisent à atteindre le plafond de requêtes en cours alors que le compte par minute paraît bas.

Lire en MarkdownDemander à ChatGPTDemander à ClaudeDemander à Perplexity