Los tres tipos de 429
HTTP 429 es el estado estándar "demasiadas peticiones". Aquí cubre tres situaciones, y el cuerpo JSON del error te dice en cuál estás.
| Código de error | Qué significa | Solución típica |
|---|---|---|
rate_limited | Demasiadas peticiones por minuto | Ralentiza, distribuye las peticiones a lo largo del minuto |
concurrency | Demasiadas peticiones ejecutándose al mismo tiempo | Reduce el paralelismo, espera a que se liberen slots |
Sobrecarga, con Retry-After: 5 | Carga temporal del servicio, no es culpa tuya | Espera el número de segundos del encabezado, luego reintenta |
Lee primero el código, porque una solución para una causa no sirve para otra. Reducir a la mitad tus peticiones por minuto no ayudará si el problema real es que 20 procesos se disparan a la vez.
Conoce tus límites
Los límites dependen del tipo de clave:
- Clave completa: 8 peticiones simultáneas y 300 peticiones por minuto.
- Clave de prueba: 2 peticiones simultáneas y 60 peticiones por minuto.
Cada respuesta incluye X-RateLimit-Limit-Requests y X-RateLimit-Limit-Concurrency, para que tu cliente pueda leer el límite superior en lugar de hardcodearlo. La clave de prueba es la causa habitual para nuevos usuarios: un script que funciona bien con 1 petición a la vez empieza a fallar cuando añades un grupo de hilos de 4. La clave de prueba está pensada para probar, y una clave completa viene con cualquier recarga desde $20 (consulta la página de precios para ver importes y bonificaciones).
Los números anteriores son por clave. Si una clave la comparte una aplicación web, un trabajo programado y el portátil de un compañero, todos consumen del mismo grupo, y los 429 parecerán aleatorios hasta que sumes las tres cargas de trabajo.
Por qué el streaming hace más probables los errores de concurrencia
Una petición normal ocupa una ranura de concurrencia durante un segundo o dos. Una petición con stream (stream: true) la ocupa hasta que llega el último token y el stream se cierra. Una respuesta larga puede mantener una ranura ocupada durante decenas de segundos, por lo que 8 ranuras desaparecen rápidamente en una aplicación de chat con varios usuarios activos.
Dos errores causan la mayoría de los problemas aquí. El primero es abandonar un stream sin cerrarlo: si el cliente deja de leer pero mantiene la conexión abierta, la ranura permanece ocupada hasta que finaliza la conexión. Cierra siempre la respuesta en un bloque finally, o usa el gestor de contexto del SDK. El segundo es reintentar un stream abriendo un segundo mientras el primero sigue activo, lo que duplica el uso de ranuras justo cuando te quedan pocas.
Si tu aplicación necesita más flujos largos simultáneos de los que permite tu clave, pon en cola las nuevas conversaciones en tu lado y muestra un estado de espera breve. Eso es mejor que dejar que los usuarios vean errores sin procesar.
Código de reintento en Python con backoff
El patrón es simple: captura el 429, lee el código, espera, reintenta con un retraso creciente y algo de aleatoriedad, y abandona tras unos intentos. Esta versión usa el paquete oficial openai contra la URL base del servicio:
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."}]))
Cuando el encabezado está presente, úsalo como espera mínima. Cuando falta, el retraso exponencial funciona para rate_limited porque la ventana por minuto avanza. El jitter evita que muchos workers reintenten al mismo instante.
Limita las llamadas paralelas para que aparezcan 429 con poca frecuencia
Los reintentos tratan el síntoma. Un semáforo evita la mayoría de los casos al no enviar más peticiones de las que permite tu número de ranuras. Ponlo un poco por debajo del límite para que un reintento o una petición perdida aún tenga espacio:
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())
Para el límite por minuto, 300 peticiones por minuto son 5 por segundo de media. Si agrupas en lotes miles de trabajos cortos, añade una pequeña pausa o un cubo de tokens antes del semáforo. Como el SDK también reintenta por defecto, establece max_retries explícitamente para que tu lógica y la del SDK no se apilen y multipliquen las esperas.
Reproduce e inspecciona un 429 con curl
Antes de cambiar el código, mira la respuesta sin procesar. Añade -i a curl para que imprima los encabezados, y dispara algunas peticiones en paralelo para provocar el error a propósito:
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
En una clave de prueba, que permite 2 peticiones a la vez, la tercera y cuarta llamadas deberían devolver un estado 429 y un código de error de concurrency. En una clave estándar necesitarías más de 8 a la vez. Mira tres cosas en cada respuesta: la línea de estado, el encabezado Retry-After si existe, y el campo error.code en el cuerpo JSON. Este pequeño experimento te dice más que una hora de suposiciones, y te da un caso reproducible para mostrar a soporte si algo parece incorrecto.
Diseña para ello, no a su alrededor
Trata un 429 como un evento normal, como un tiempo de espera agotado. Pon las llamadas al modelo detrás de una única función, registra cada reintento con su motivo, y expone un contador para que notes cuando los reintentos aumentan. Una tasa de reintentos creciente es una señal temprana de que tu tráfico ha superado los límites de una sola clave, mucho antes de que los usuarios se quejen. Para productos de chat, una pequeña cola en memoria por usuario evita que una cuenta ocupada se lleve todas las 8 ranuras de los demás.
Una lista de verificación de depuración breve
- Registra el cuerpo completo del error y el encabezado
X-Request-Idpara cada 429. El campo code separarate_limiteddeconcurrency. - Comprueba si tu clave es una clave de prueba. Si es así, prevé 2 peticiones simultáneas y 60 por minuto.
- Cuenta cada programa que usa la clave, no solo el que falló.
- Busca flujos sin cerrar, y bucles que reintentan al instante sin retraso. Un bucle de reintento instantáneo convierte un 429 en cien.
- Confirma el saldo con
X-Balance-USDoGET /v1/balance. Un saldo vacío es un problema diferente a un 429, pero comprobarlo toma segundos.
Las peticiones fallidas no se cobran, por lo que reintentar no te cuesta tokens para los intentos rechazados. Para la lista completa de códigos de estado y encabezados, consulta la documentación. Si necesitas una clave con límites superiores a una de prueba, consigue una clave de API y recarga.
