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:
- Ponga los trabajos en una cola compartida (Redis, SQS, una tabla de base de datos).
- Ejecute un número fijo de consumidores igual al límite de solicitudes en curso de la clave.
- Dé a cada trabajo un ID y guarde los resultados por ID, para que un trabajo reintentado no se ejecute dos veces.
- 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.
