Presentación

Al efectuar integraciones con nuestras API, los clientes pueden recibir ocasionalmente una respuesta HTTP 429 – Demasiadas solicitudes.
Esto indica que la tasa de solicitudes del cliente ha superado temporalmente los límites permitidos.

Nuestra implementación de limitación de tasa está diseñada para proteger la estabilidad del sistema y asegurar un uso justo entre todos los clientes.

Este artículo describe cómo funciona el limitador de tasa y cómo las aplicaciones de los clientes deben manejar de forma segura las respuestas 429.

Modelo de limitación de tasa (token bucket)

Los límites de tasa se aplican por identidad:

• Solicitudes autenticadas → por ID de usuario
• Solicitudes no autenticadas → por dirección IP

Cada identidad tiene un token bucket:

• Cada solicitud consume un token
• Los tokens se recargan a una tasa fija de tokens por segundo
• Cuando no quedan tokens → la API responde con HTTP 429
• Una vez que los tokens se acumulan de nuevo → las solicitudes se efectúan normalmente

Gestión de las respuestas 429: retroceso exponencial con jitter

Los clientes deben implementar un retroceso exponencial con jitter, ya que la API no especifica cuánto tiempo esperar antes de efectuar un reintento.

Programación de retroceso recomendada

¿Por qué jitter?

Sin aleatoriedad, múltiples clientes reintentan al mismo tiempo → causando ráfagas sincronizadas que pueden generar más 429 y desestabilizar el sistema.
El jitter distribuye los intentos de reintento en el tiempo y estabiliza la recuperación.

Límite máximo de reintentos

Para evitar bucles infinitos de reintentos o fallos en cascada:

• Retraso máximo: 30–60 segundos
• Número máximo de intentos: 5–7
• Después de superar el límite → se deja de reintentar y se devuelve un error hacia arriba.

Lo que no se debe hacer

Los clientes deben evitar el siguiente comportamiento:

❌ No reintentar inmediatamente después de un 429
❌ No reintentar solicitudes en paralelo
❌ No incrementar abruptamente el volumen de solicitudes tras la recuperación
❌ No asumir ninguna ventana o cuota de tasa fija
(por ejemplo, “podemos hacer 10 solicitudes/seg” o “el límite se reinicia en :00”)

Ejemplo de pseudocódigo

A continuación se muestra un ejemplo genérico de pseudocódigo que ilustra una forma de implementar el retroceso exponencial con jitter.

Retroceso exponencial básico con jitter

function sendWithRetry(request):
    baseDelay = 500  // ms
    maxDelay = 60000 // ms
    maxAttempts = 7
    attempt = 0
    while attempt < maxAttempts:
        response = sendHttpRequest(request)
        if response.status != 429:
            return response
        attempt += 1
        // exponential delay
        delay = baseDelay * (2 ^ (attempt - 1))
        // jitter ±50%
        jitter = randomBetween(0.5, 1.5)
        delay = delay * jitter
        delay = min(delay, maxDelay)
        sleep(delay)
    throw "Max retry attempts exceeded"

Lo que el limitador de tasa no proporciona

Nuestra implementación actual de limitación de tasa no devuelve:

• Encabezado Retry-After
• Cuota restante para la ventana actual
• Información sobre el tamaño o límites de la ventana temporal

Los clientes deben implementar su propia lógica de retroceso y tratar cada 429 como una señal para reducir temporalmente la tasa de solicitudes.

Resumen

• Un HTTP 429 indica que la tasa de solicitudes ha superado los límites permitidos.
• El servidor no indica cuánto tiempo esperar antes de reintentar.
• Los clientes deben implementar retroceso exponencial con jitter, con límites estrictos de reintentos.
• Evite los reintentos en paralelo y suposiciones sobre ventanas de tasa.
• El pseudocódigo anterior ilustra un comportamiento de reintento correcto y seguro.