FR ▾
Obtenir une clé API

Erreur 429 de l'API LLM : causes et comment la corriger

Une erreur 429 de l'API LLM signifie que le serveur refuse une requête pour le moment, pas à jamais. Sur cette API, il existe trois causes distinctes, chacune nécessitant une correction légèrement différente.

Mis à jour le

Paquets de lumière en file d'attente à une porte avec huit voies, illustrant les limites de débit de l'API

Points clés

Les trois types d'erreur 429

HTTP 429 est le statut standard "trop de requêtes". Ici, il couvre trois situations, et le corps JSON de l'erreur indique laquelle vous concerne.

Code d'erreurCe que cela signifieCorrection typique
rate_limitedTrop de requêtes par minuteRalentir, répartir les requêtes sur la minute
concurrencyTrop de requêtes s'exécutant en même tempsRéduire le parallélisme, attendre que des slots se libèrent
Surcharge, avec Retry-After: 5Charge temporaire du service, pas de votre fauteAttendre le nombre de secondes indiqué dans l'en-tête, puis réessayer

Lisez d'abord le code, car une correction pour une cause ne sert à rien pour une autre. Diviser par deux vos requêtes par minute n'aidera pas si le vrai problème est 20 workers tirant en même temps.

Connaître vos limites

Les limites dépendent du type de clé :

  • Clé complète : 8 requêtes simultanées et 300 requêtes par minute.
  • Clé d'essai : 2 requêtes simultanées et 60 requêtes par minute.

Chaque réponse inclut les en-têtes X-RateLimit-Limit-Requests et X-RateLimit-Limit-Concurrency, afin que votre client puisse lire le plafond au lieu de le coder en dur. La clé d’essai est souvent la cause chez les nouveaux utilisateurs : un script qui fonctionne bien avec 1 requête à la fois commence à échouer lorsque vous ajoutez un groupe de threads de 4. L’essai est prévu pour les tests, et une clé complète est fournie avec tout rechargement à partir de $20 (voir la page tarifaire pour les montants et les bonus).

Les chiffres ci-dessus sont par clé. Si une clé est partagée par une application web, une tâche cron et le notebook d'un collègue, ils puisent tous dans le même pool, et les 429 sembleront aléatoires jusqu'à ce que vous additionnez les trois tâches.

Pourquoi le streaming rend les erreurs de concurrence plus probables

Une requête normale occupe un slot de concurrence pendant une ou deux secondes. Une requête en streaming (stream: true) l'occupe jusqu'à ce que le dernier token arrive et que le flux se ferme. Une longue réponse peut garder un slot occupé pendant des dizaines de secondes, donc 8 slots disparaissent rapidement dans une application de chat avec plusieurs utilisateurs actifs.

Deux erreurs causent la plupart des problèmes ici. La première est l'abandon d'un flux sans le fermer : si le client arrête de lire mais laisse la connexion ouverte, le slot reste occupé jusqu'à la fin de la connexion. Fermez toujours la réponse dans un bloc finally, ou utilisez le gestionnaire de contexte du SDK. La seconde est le réessai d'un flux en ouvrant un second pendant que le premier est encore vivant, ce qui double l'utilisation des slots exactement lorsque vous en manquez.

Si votre application a besoin de plus de longs flux simultanés que ce que votre clé permet, mettez en file d'attente les nouveaux chats de votre côté et affichez un état d'attente court. C'est mieux que de laisser les utilisateurs voir des erreurs brutes.

Code de réessai Python avec attente exponentielle

Le modèle est simple : attraper le 429, lire le code, attendre, réessayer avec un délai croissant et un peu d'aléatoire, et abandonner après quelques tentatives. Cette version utilise le package officiel openai contre l'URL de base du service :

import random
import time
from openai import OpenAI, RateLimitError

client = OpenAI(
    base_url="https://api.onekeyllmapi.com/v1",
    api_key="YOUR_KEY",
    max_retries=0,  # we handle retries ourselves
)

def chat(messages, attempts=5):
    for i in range(attempts):
        try:
            r = client.chat.completions.create(
                model="uncensored",
                messages=messages,
            )
            return r.choices[0].message.content
        except RateLimitError as e:
            headers = e.response.headers
            wait = float(headers.get("Retry-After", 0))
            if not wait:
                wait = min(30, 2 ** i)  # 1, 2, 4, 8, 16 seconds
            wait += random.uniform(0, 1)  # jitter
            time.sleep(wait)
    raise RuntimeError("still rate limited after retries")

print(chat([{"role": "user", "content": "Reply with the word ok."}]))

Lorsque l’en-tête est présent, utilisez-le comme délai minimum. Lorsqu’il est absent, le délai exponentiel fonctionne pour rate_limited car la fenêtre par minute évolue. L'aléa évite que de nombreux workers ne réessayent tous au même instant.

Limitez les appels parallèles pour voir rarement un 429

Les retries traitent le symptôme. Un sémaphore évite la plupart du problème en n'envoyant jamais plus que votre nombre de slots. Réglez-le légèrement en dessous de la limite pour qu'un retry ou une requête errante ait encore de la place :

import asyncio
from openai import AsyncOpenAI

client = AsyncOpenAI(
    base_url="https://api.onekeyllmapi.com/v1",
    api_key="YOUR_KEY",
)
sem = asyncio.Semaphore(6)  # full key allows 8; use 1 on a trial key

async def ask(prompt):
    async with sem:
        r = await client.chat.completions.create(
            model="uncensored",
            messages=[{"role": "user", "content": prompt}],
        )
        return r.choices[0].message.content

async def main():
    prompts = [f"Give one fact about the number {n}." for n in range(50)]
    results = await asyncio.gather(*(ask(p) for p in prompts))
    print(len(results))

asyncio.run(main())

Pour la limite par minute, 300 requêtes par minute font 5 par seconde en moyenne. Si vous regroupez des milliers de tâches courtes, ajoutez une petite pause ou un token bucket devant le sémaphore. Comme le SDK réessaie aussi de lui-même par défaut, réglez max_retries explicitement pour que votre logique et celle du SDK ne s'empilent pas et ne multiplient pas les attentes.

Reproduire et inspecter un 429 avec curl

Avant de modifier le code, regardez la réponse brute. Ajoutez -i à curl pour imprimer les en-têtes, et lancez quelques requêtes en parallèle pour provoquer l'erreur intentionnellement :

for i in 1 2 3 4; do
  curl -i -s https://api.onekeyllmapi.com/v1/chat/completions     -H "Authorization: Bearer $API_KEY"     -H "Content-Type: application/json"     -d '{"model":"uncensored","messages":[{"role":"user","content":"Count to 200 slowly."}]}' &
done
wait

Sur une clé d'essai, qui permet 2 requêtes à la fois, les troisième et quatrième appels devraient retourner le statut 429 et un code d'erreur de concurrency. Sur une clé payante, vous auriez besoin de plus de 8 en même temps. Regardez trois choses dans chaque réponse : la ligne de statut, l'en-tête Retry-After s'il y en a un, et le champ error.code dans le corps JSON. Cette petite expérience en dit plus qu'une heure de devinettes, et elle vous donne un cas reproductible à montrer au support si quelque chose semble faux.

Concevez pour cela, pas autour

Traitez un 429 comme un événement normal, comme un timeout. Placez les appels modèle derrière une seule fonction, journalisez chaque retry avec sa raison, et exposez un compteur pour remarquer quand les retries augmentent. Un taux de retry croissant est un signe précoce que votre trafic a dépassé les limites d'une seule clé, bien avant les plaintes des utilisateurs. Pour les produits de chat, une petite file d'attente en mémoire par utilisateur empêche un compte occupé de prendre tous les 8 slots des autres.

Une courte liste de vérification de débogage

  1. Journalisez le corps d'erreur complet et l'en-tête X-Request-Id pour chaque 429. Le champ code sépare rate_limited de concurrency.
  2. Vérifiez si votre clé est une clé d'essai. Si oui, attendez 2 requêtes simultanées et 60 par minute.
  3. Comptez tous les programmes qui utilisent la clé, pas seulement celui qui a échoué.
  4. Recherchez les flux non fermés, et les boucles qui réessaient instantanément sans délai. Une boucle de retry instantanée transforme un 429 en cent.
  5. Confirmez le solde avec X-Balance-USD ou GET /v1/balance. Un solde vide est un problème différent d'un 429, mais la vérification prend quelques secondes.

Les requêtes échouées ne sont pas facturées, donc réessayer ne vous coûte pas de tokens pour les tentatives rejetées. Pour la liste complète des codes d'état et des en-têtes, consultez la documentation. Si vous avez besoin d'une clé avec des limites supérieures à celle d'un essai, obtenez une clé API et rechargez.

Questions et réponses

L'erreur 429 est-elle de votre fait ou celui du fournisseur ?

Les deux sont possibles. Les codes rate_limited et concurrency indiquent que votre clé a dépassé sa limite. Un 429 avec un en-tête Retry-After peut aussi provenir d'une surcharge temporaire ; attendre la durée indiquée puis réessayer est la bonne réponse.

Combien de temps dois-je attendre avant de réessayer ?

Si la réponse contient un en-tête Retry-After, attendez au moins ce nombre de secondes. Sinon, commencez à une seconde et doublez le délai à chaque fois, avec une petite variation aléatoire.

Les requêtes rejetées coûtent-elles de l'argent ?

Non. Les requêtes échouées ou refusées ne sont pas facturées.

Puis-je augmenter mes limites ?

Une clé complète permet 8 requêtes simultanées et 300 par minute, contre 2 et 60 pour une clé d'essai. Au-delà, répartissez le travail sur une file d'attente de votre côté.

Votre clé est à un formulaire d'ici

Créez un compte, copiez la clé, modifiez l'URL de base. C'est toute la configuration.