Inicio → Ayuda

Leer bien un 429: retry-after y las cabeceras de límite

Un 429 normalmente lleva una cabecera Retry-After, en segundos, y a menudo un conjunto de cabeceras que indican qué límite se agotó y cuándo se restablece. Esperar ese tiempo lo despeja; reintentar de inmediato lo alarga.

Lo que ves

429 Too Many Requests with no obvious pattern
Retries make the problem worse
Only some requests fail while others succeed at the same moment
Rate limiting under a load that used to be fine

Por qué ocurre

Los proveedores miden varias dimensiones a la vez: peticiones por minuto, tokens por minuto y a veces peticiones simultáneas. Alcanzar el límite de tokens estando muy por debajo del de peticiones es la razón de que fallen «solo algunas peticiones».

Los límites de tokens cuentan lo que envías más lo que reservas. Unas pocas peticiones con un max_tokens grande pueden agotar el presupuesto de tokens por minuto mientras el número de peticiones parece insignificante.

Los reintentos inmediatos también cuentan. Un bucle de reintentos apretado convierte una pausa de un segundo en un bloqueo sostenido, que es la razón habitual de que un 429 pasajero se vuelva permanente.

Comprueba si es esta la causa

Cuando recibas un 429, imprime las cabeceras en lugar del cuerpo:

curl -s -D- -o /dev/null -X POST 'YOUR_BASE_URL/chat/completions' \
  -H 'Authorization: Bearer YOUR_KEY' -H 'Content-Type: application/json' \
  -d '{"model":"MODEL","messages":[{"role":"user","content":"hi"}]}' \
  | grep -i 'retry-after\|ratelimit\|^HTTP'

Respeta Retry-After cuando esté presente. Si no está, un backoff exponencial con jitter empezando en torno a un segundo es el valor seguro por defecto.

Cómo solucionarlo

Respeta Retry-After antes que tu propio backoffSi la cabecera dice 12 segundos, esperar 12 segundos funciona. Tu backoff de un segundo no, y además te cuesta el siguiente intento.
Añade jitterSin un desfase aleatorio, todos los clientes de tu flota reintentan al unísono y reconstruyen el pico del que te estás retirando.
Comprueba si en realidad es un problema de saldoAlgunas pasarelas devuelven 429 cuando la cuenta está vacía. Ese nunca se despeja al reintentar: lee el cuerpo del error antes de suponer que es limitación de velocidad.

En APICLAN un 429 por saldo vacío y un 429 por congestión del upstream dicen cosas distintas en el cuerpo. El primero necesita una recarga y nunca funcionará al reintentar; el segundo suele despejarse en segundos.

Relacionado

Unexpected token '<' al llamar a una API compatible con OpenAI 401 invalid API key: cuando la clave parece correcta pero sigue fallando

Revisado por última vez el 2026-10-01. Escrito a partir de problemas diagnosticados en una pasarela compatible con OpenAI en producción, no recopilado de otras webs.