ES ▾
Obtener clave de API

Error 429 de la API LLM: causas y cómo solucionarlo

Un error 429 de la API LLM significa que el servidor rechaza una petición por ahora, no para siempre. En esta API hay tres causas distintas, y cada una requiere una solución ligeramente diferente.

Actualizado

Paquetes de luz haciendo cola en una puerta con ocho carriles, ilustrando los límites de peticiones de la API

Puntos clave

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 errorQué significaSolución típica
rate_limitedDemasiadas peticiones por minutoRalentiza, distribuye las peticiones a lo largo del minuto
concurrencyDemasiadas peticiones ejecutándose al mismo tiempoReduce el paralelismo, espera a que se liberen slots
Sobrecarga, con Retry-After: 5Carga temporal del servicio, no es culpa tuyaEspera 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

  1. Registra el cuerpo completo del error y el encabezado X-Request-Id para cada 429. El campo code separa rate_limited de concurrency.
  2. Comprueba si tu clave es una clave de prueba. Si es así, prevé 2 peticiones simultáneas y 60 por minuto.
  3. Cuenta cada programa que usa la clave, no solo el que falló.
  4. Busca flujos sin cerrar, y bucles que reintentan al instante sin retraso. Un bucle de reintento instantáneo convierte un 429 en cien.
  5. Confirma el saldo con X-Balance-USD o GET /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.

Preguntas y respuestas

¿Es culpa mía o del proveedor un 429?

Ambas son posibles. Los códigos rate_limited y concurrency indican que tu clave superó su límite. Un 429 con un encabezado Retry-After también puede deberse a una sobrecarga temporal; esperar el tiempo indicado y reintentar es la respuesta correcta.

¿Cuánto debo esperar antes de reintentar?

Si la respuesta tiene un encabezado Retry-After, espera al menos ese número de segundos. Si no, empieza con un segundo y duplica el retraso cada vez, con un poco de jitter aleatorio.

¿Cuestan dinero las peticiones rechazadas?

No. Las peticiones fallidas o rechazadas no se cobran.

¿Puedo aumentar mis límites?

Una clave completa permite 8 solicitudes concurrentes y 300 por minuto, frente a 2 y 60 para una clave de prueba. Más allá de eso, distribuye el trabajo en una cola en tu lado.

Tu clave está a un paso de distancia

Crea una cuenta, copia la clave, cambia la URL base. Esa es toda la configuración.