BroadRouter

Cómo manejar el 429 de una API de LLM: backoff, jitter y limitadores

Por el equipo de BroadNet Inference · 5 min de lectura · Publicado · Actualizado

Un 429 significa que alcanzó un límite de frecuencia, de concurrencia o de gasto. Reinténtelo con backoff exponencial acotado y jitter aleatorio, y respete Retry-After si llega. Después evite la mayoría de los 429: limite las solicitudes en curso con un semáforo al límite de la clave y ponga el resto en cola. Reintente los 5xx igual; los demás 4xx, corríjalos.

Un 429 significa que su tráfico superó un límite de frecuencia: solicitudes por minuto, solicitudes en curso, tokens por minuto o gasto. Se resuelve en dos mitades. Reintentar bien: backoff exponencial acotado con jitter aleatorio, respetando Retry-After. Enviar menos a la vez: un semáforo al límite de solicitudes en curso de la clave, más una cola. Encontrará ambas abajo, con código.

Para una referencia completa de códigos de estado, consulte la guía de errores y reintentos; para ejecuciones de agentes de varias horas con puntos de control y tiempos de espera, consulte agentes de larga duración: tiempos de espera y reintentos.

¿Qué diferencia hay entre 429 y 5xx?

Estado De quién es el problema ¿Reintentar? Cómo
429 Su tráfico superó un límite Sí Backoff con jitter; respete Retry-After; reduzca la concurrencia
500 / 502 / 503 / 504 Del lado del servidor Sí Backoff exponencial acotado
Conexión restablecida, tiempo de espera agotado Red o servidor Normalmente Backoff; en streams, solo si una nueva factura es aceptable
400 / 422 Solicitud incorrecta No Corrija el contenido de la solicitud
401 / 402 / 403 Clave, saldo o política No Corrija la clave, recargue la cuenta o corrija la lista de permitidos
413 Solicitud demasiado grande No Redúzcala

En BroadNet Inference, un 429 puede deberse a cualquiera de cuatro límites: frecuencia, concurrencia, tasa de tokens o gasto. Un límite de gasto no se despeja en 30 segundos. La documentación de BroadNet no indica qué campo del cuerpo del error nombra el límite, así que registre el cuerpo y compárelo con los límites que aparecen en los detalles de su clave.

Nuestro conjunto de datos abierto de niveles gratuitos y límites de frecuencia de API de LLM compara lo que publican 14 proveedores sobre acceso gratuito, límites de frecuencia iniciales, requisito de tarjeta y entrenamiento con datos del nivel gratuito, con la fuente y la fecha de cada valor.

¿Qué límites provocan los 429?

Conozca los números con los que trabaja. En BroadNet Inference:

Tipo de clave Solicitudes / minuto En curso Otros
Pago por uso 30 4 Presupuesto de gasto compartido
Clave por hora 120 1 stream 300,000 tokens / minuto
Sesión de plan ilimitado — 1 solicitud por sesión Sin medidor de tokens

El número de solicitudes en curso es el que más importa en los LLM. Una respuesta en streaming ocupa su plaza hasta que llega el último token, así que una respuesta larga la mantiene ocupada todo el tiempo que el modelo tarde en escribirla (BroadNet indica una velocidad típica de unos 100 tokens por segundo). Si envía más llamadas en paralelo que las 4 plazas de la clave, las que sobran reciben un 429, aunque solo haya enviado unas pocas solicitudes ese minuto. Es un problema de concurrencia, y el backoff por sí solo lo resuelve mal. Para dimensionar los workers según un límite antes del lanzamiento, use la calculadora de límites de frecuencia de LLM, gratuita. Para un trabajo fijo de muchos elementos, el planificador de trabajos por lotes de LLM convierte esos mismos límites en un tiempo de ejecución. Otros proveedores cuentan de forma distinta (tokens por minuto, solicitudes por día o solicitudes en curso); límites de frecuencia de API de LLM por proveedor compara 13 de ellos según su propia documentación.

¿Cómo se escribe un backoff con jitter?

El backoff exponencial simple espera 1, 2, 4 y 8 segundos. Si cien workers fueron limitados en el mismo momento, todos vuelven en el mismo momento. La simulación de AWS con 100 clientes en competencia mostró que el full jitter redujo el número de llamadas a menos de la mitad y terminó antes que el backoff sin jitter. La versión más sencilla, el full jitter, espera un tiempo aleatorio entre cero y el tope exponencial:

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 desactiva los reintentos propios del SDK para que no reintente dos veces. Si le basta con el comportamiento integrado del SDK, lo contrario también funciona: prescinda de su bucle y configure max_retries=4 en el cliente, como muestra la guía del SDK de Python. Los SDK oficiales de Python y Node reintentan por defecto dos veces los errores de conexión, 408, 409, 429 y 5xx.

Retry-After es un encabezado estándar (RFC 9110) que puede contener segundos o una fecha. La documentación de BroadNet no lo garantiza, así que el código lo trata como opcional.

¿Cómo evitar los 429 antes de que ocurran?

Limite las solicitudes en curso al límite de la clave. En Python, un asyncio.Semaphore lo hace con un objeto y un bloque async with. El código usa 4 como ejemplo; ajústelo al límite de solicitudes en curso de su clave (4 en una clave de pago por uso de BroadNet):

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 inicia todas las tareas, pero solo se ejecutan a la vez tantas como permita el semáforo. El resto espera en la cola del semáforo. En Node, el paquete p-limit hace lo mismo, de nuevo con 4 como valor de ejemplo:

// 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))));

Si además necesita un tope por minuto, añada un token bucket que libere un permiso cada 60 / rpm segundos, donde rpm es el límite de solicitudes por minuto de su clave (30 en una clave de pago por uso de BroadNet).

¿Cuándo necesita una cola de verdad?

Un semáforo vive dentro de un proceso. Cuando varios workers o servidores comparten una clave, el límite es compartido y cada proceso solo ve su propio tráfico. Entonces:

  1. Ponga los trabajos en una cola compartida (Redis, SQS, una tabla de base de datos).
  2. Ejecute un número fijo de consumidores igual al límite de solicitudes en curso de la clave.
  3. Dé a cada trabajo un ID y guarde los resultados por ID, para que un trabajo reintentado no se ejecute dos veces.
  4. Envíe el tráfico interactivo y el de lotes por claves o colas separadas, para que una acumulación de lotes nunca bloquee a un usuario que espera una respuesta.

Para un trabajo masivo de miles de elementos sin Batch API, consulte el ejecutor de lotes reanudable.

¿Qué errores de reintento convierten los 429 en caídas?

  • Reintentos sin límite. Un bucle de reintentos sin tope durante una caída larga multiplica su carga y, con facturación por token, su factura.
  • Reintentar a ciegas un stream a medio terminar. Si el stream ya devolvió tokens, un reintento es una inferencia nueva y el usuario puede ver el texto dos veces. Consulte el artículo sobre streaming para detectar streams incompletos.
  • Reintentar errores de cuenta. Un 401 por una asignación de pago por uso agotada o un 402 por saldo insuficiente no se resolverán solos.

Registre cada reintento con su estado, el tiempo de espera y el encabezado de respuesta X-Request-ID, que la documentación de BroadNet pide conservar para soporte. Una tasa de reintentos en aumento es la primera señal de que necesita más capacidad; el registro de uso muestra cómo anotarla.

Dónde encaja BroadNet Inference

Los límites de BroadNet están publicados y son lo bastante pequeños como para diseñar en torno a ellos: 4 solicitudes en curso con una clave de pago por uso. Eso sirve para aplicaciones y agentes, y se queda corto para un trabajo masivo que quiera cientos de llamadas en paralelo con una sola clave. Para agentes, un plan ilimitado no tiene medidor de tokens y ejecuta una solicitud a la vez por sesión; para trabajar en paralelo se añaden sesiones, como se describe en ejecutar agentes de programación en paralelo. Los límites actuales están en la referencia de la API.

Preguntas frecuentes

¿Qué significa el error HTTP 429 en una API de LLM?

Too Many Requests («demasiadas solicitudes»). Superó un límite de solicitudes por minuto, de solicitudes en curso, de tokens por minuto o de gasto. La solicitud no se procesó, así que es seguro enviarla de nuevo tras una espera.

¿Cuánto debo esperar antes de reintentar un 429?

Use Retry-After si el servidor lo envía. Si no, empiece con alrededor de un segundo, duplique la espera en cada intento, ponga un tope de unos 30 a 60 segundos y elija una espera aleatoria entre cero y ese tope. Deténgase tras cuatro a seis intentos.

¿Debo reintentar los errores 500 y 503 de una API de LLM?

Sí, con el mismo backoff acotado. Son errores del lado del servidor. Un 400, 401, 403 o 422 fallará igual cada vez, así que corríjalo.

¿El SDK de OpenAI reintenta los 429 automáticamente?

Sí. Los SDK oficiales de Python y Node reintentan por defecto dos veces los errores de conexión, 408, 409, 429 y 5xx, con un backoff exponencial corto. Suba max_retries para trabajos por lotes y añada su propio límite de concurrencia.

¿Por qué recibo un 429 si estoy por debajo del límite de solicitudes por minuto?

Normalmente por el límite de concurrencia. Las respuestas largas en streaming siguen en curso durante muchos segundos, así que unas pocas llamadas en paralelo pueden alcanzar el tope de solicitudes en curso aunque el recuento por minuto parezca bajo.

Leer en MarkdownPreguntar a ChatGPTPreguntar a ClaudePreguntar a Perplexity