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'erreur | Ce que cela signifie | Correction typique |
|---|---|---|
rate_limited | Trop de requêtes par minute | Ralentir, répartir les requêtes sur la minute |
concurrency | Trop de requêtes s'exécutant en même temps | Réduire le parallélisme, attendre que des slots se libèrent |
Surcharge, avec Retry-After: 5 | Charge temporaire du service, pas de votre faute | Attendre 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
- Journalisez le corps d'erreur complet et l'en-tête
X-Request-Idpour chaque 429. Le champ code séparerate_limiteddeconcurrency. - Vérifiez si votre clé est une clé d'essai. Si oui, attendez 2 requêtes simultanées et 60 par minute.
- Comptez tous les programmes qui utilisent la clé, pas seulement celui qui a échoué.
- 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.
- Confirmez le solde avec
X-Balance-USDouGET /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.
