Un script con errores llama a su API en un bucle cerrado. Sin límites, puede ralentizar el servicio para todos los demás usuarios o generar una gran factura de la nube. La limitación de la tasa API es la barrera que impide que un solo cliente obtenga más de lo que le corresponde.

Para mostrar cómo se comportan los algoritmos comunes, escribimos pequeñas versiones de Python y las alimentamos con tiempos de solicitud simulados. Los resultados a continuación provienen de esa ejecución. Son modelos de enseñanza, no códigos de producción, y las puertas de enlace reales tienen más funciones.

¿Qué es la limitación de velocidad?

La limitación de velocidad cuenta las solicitudes por cliente y rechaza o retrasa las solicitudes que superan un límite acordado, como 100 solicitudes por minuto. Una idea relacionada, limitar, a menudo significa ralentizar las solicitudes en lugar de rechazarlas. Una cuota suele ser una asignación mayor durante un período más largo, como 10 000 llamadas por mes en un plan de precios.

Por qué las API lo necesitan

• Estabilidad: los picos de tráfico no pueden abrumar las bases de datos ni los servicios posteriores.
• Equidad: un cliente pesado no puede matar de hambre a los demás.
• Seguridad: los límites ralentizan los intentos de inicio de sesión por fuerza bruta y el raspado.
• Control de costos: las operaciones costosas, como las llamadas a modelos de IA, se mantienen dentro del presupuesto.

La limitación de velocidad es un control central en el Top 10 de seguridad de API de OWASP, bajo consumo de recursos sin restricciones. Nuestra guía de Prueba de API con Postman muestra cómo enviar las solicitudes repetidas necesarias para comprobarlo.

Cubo de fichas

Imagínese un cubo que contiene hasta 5 fichas. Cada solicitud requiere un token. Los tokens se recargan a 1 por segundo y el depósito nunca contiene más de 5. Si el depósito está vacío, la solicitud se rechaza.

class TokenBucket:
    def __init__(self, capacity, refill_per_sec):
        self.capacity = capacity
        self.rate = refill_per_sec
        self.tokens = capacity
        self.last = 0.0

    def allow(self, now):
        elapsed = now - self.last
        self.tokens = min(self.capacity, self.tokens + elapsed * self.rate)
        self.last = now
        if self.tokens >= 1:
            self.tokens -= 1
            return True
        return False

Enviamos 7 solicitudes a la vez y luego más:

burst of 7 at t=0:  [True, True, True, True, True, False, False]
t=2.0:              [True, True, False]
t=10:               5 allowed of 10

Los primeros 5 salieron como una ráfaga, luego el cubo quedó vacío. Dos segundos después, se habían recargado 2 tokens, por lo que se aprobaron 2 solicitudes más. Después de una larga pausa, el depósito se llenó nuevamente, pero con un límite de 5. Este comportamiento de ráfaga y luego constante se adapta al tráfico real, razón por la cual los depósitos de tokens son comunes en las puertas de enlace API. El depósito con fugas es un pariente cercano que procesa solicitudes a una velocidad fija, suavizando la salida en lugar de permitir ráfagas.

Ventana fija vs ventana corredera

Un contador de ventana fija es el enfoque más simple: permita 10 solicitudes por minuto y reinicie el contador cuando cambie el minuto. Tiene un defecto conocido en el límite. Enviamos 10 solicitudes a los 59,9 segundos y 10 más a los 60,0 segundos, con un límite de 10 por ventana de 60 segundos:

fixed window allowed around boundary: 20 of 20
sliding log allowed around boundary:  10 of 20

La ventana fija permitió las 20 solicitudes en una décima de segundo, el doble de la velocidad prevista, porque caían en dos ventanas diferentes. Un registro deslizante recuerda la hora de cada solicitud reciente y cuenta las de los últimos 60 segundos, por lo que solo permitió 10 correctamente.

La compensación es la memoria. Un registro deslizante almacena una marca de tiempo por solicitud. El mostrador con ventana corrediza es un término medio popular. Estima la tasa combinando los recuentos de ventanas actuales y anteriores, utilizando poca memoria con buena precisión.

Comparación de algoritmos

Que limitar por

• Clave API o ID de usuario: la opción más justa para API autenticadas.
• Dirección IP: útil para puntos finales públicos, pero muchos usuarios pueden compartir una IP y los atacantes pueden rotarlas.
• Punto final: las operaciones costosas, como la búsqueda, las exportaciones o el inicio de sesión, merecen límites más estrictos.
• Nivel del plan: los clientes gratuitos y pagos suelen obtener límites diferentes.

Los puntos finales de inicio de sesión necesitan atención especial. Limite tanto por cuenta como por IP, de modo que los atacantes no puedan simplemente distribuir conjeturas entre muchas IP o muchas cuentas.

La respuesta 429

Cuando un cliente supera el límite, devuelva HTTP 429 Demasiadas solicitudes, no 500 o 403. Incluya encabezados que le indiquen al cliente qué sucedió y cuándo volver a intentarlo. Nuestra simulación produjo este conjunto para un cliente al que no le quedaban solicitudes:

HTTP/1.1 429 Too Many Requests
RateLimit-Limit: 100
RateLimit-Remaining: 0
RateLimit-Reset: 30
Retry-After: 30

Retry-After es un encabezado HTTP estándar. Los encabezados RateLimit-* provienen de un borrador del IETF y muchas API utilizan sus propias variantes X-RateLimit-*. Elijas lo que elijas, documentalo. Para obtener más información sobre los códigos de estado, consulte nuestra hoja de referencia sobre códigos de estado HTTP.

Manejar los límites como cliente

Volver a intentarlo inmediatamente después de un 429 empeora las cosas. Si miles de clientes lo hacen al mismo tiempo, llegan al servidor en ondas sincronizadas. La solución es retroceso exponencial con fluctuación: espere más después de cada falla y agregue aleatoriedad.

def backoff(attempt, base=0.5, cap=30, rng=random.Random(4)):
    return round(min(cap, base * 2 ** attempt) * rng.random(), 2)

[backoff(a) for a in range(6)]
# [0.12, 0.1, 0.79, 0.62, 0.53, 6.43]

Esto es “full jitter”: una espera aleatoria entre cero y un techo que crece exponencialmente. Las esperas parecen irregulares, y ese es el punto. Los clientes se dispersan en lugar de volver a intentarlo juntos. Sembramos el generador aleatorio para que se pudiera reproducir la salida.

Limitación de tasa distribuida

Con varios servidores API detrás de un equilibrador de carga, cada servidor por sí solo permite que un cliente supere el límite al distribuir las solicitudes entre ellos. Los equipos suelen mantener contadores en una tienda compartida como Redis, con operaciones atómicas o un script corto para que dos servidores no puedan tomar el último token. Las puertas de enlace como Kong, NGINX, Envoy y las puertas de enlace API en la nube proporcionan esto como configuración. No ejecutamos una configuración distribuida para este artículo.

Límites de tasa de prueba

• Envíe solicitudes hasta el límite y confirme que tienen éxito.
• Envíe uno más y confirme un 429 con los encabezados correctos.
• Espere el tiempo de reinicio y confirme que las solicitudes se hayan realizado nuevamente.
• Verificar límites por clave: el uso de un cliente no debe bloquear a otro.
• Pruebe el límite entre ventanas para detectar el problema de la doble ráfaga.
• Utilice una herramienta de carga, como se explica en pruebas de carga frente a pruebas de estrés, para comprobar el comportamiento en condiciones de alta concurrencia.

En las pruebas unitarias, inyecte la hora actual, como lo hace nuestra simulación con now, para que las pruebas nunca tengan que dormir.

Diseñar límites con los que los usuarios puedan vivir

Elegir los números es tan importante como elegir el algoritmo. Comience con tráfico real: observe cuántas solicitudes realizan por minuto sus clientes legítimos más importantes y establezca límites cómodamente por encima de eso. Un límite que bloquea el uso normal genera tickets de soporte, no seguridad.

• Publique los límites en la documentación de su API, por punto final y por plan.
• Advertir antes de bloquear. Los encabezados que muestran las solicitudes restantes permiten que los clientes con buen comportamiento disminuyan la velocidad por sí solos.
• Ofrezca alternativas a las encuestas intensas, como webhooks, puntos finales masivos o páginas más grandes.
• Supervise las tarifas de 429. Un aumento repentino puede significar un ataque, la liberación de un cliente con errores o límites que ahora son demasiado estrictos.
• Otorgar excepciones deliberadamente, por ejemplo, límites elevados para un socio, registrados en la configuración en lugar de codificados.

Decida también qué sucede con las solicitudes que llegan justo por encima del límite. Algunas API ponen en cola brevemente una pequeña cantidad de solicitudes adicionales en lugar de rechazarlas, lo que suaviza los picos breves. Otros dan prioridad a puntos finales esenciales, como los pagos, sobre otros menos críticos como los análisis, de modo que el tráfico importante siga fluyendo cuando el sistema está bajo presión.

Conclusión

Una buena limitación de tasa es un contrato entre API y cliente. El servidor elige un algoritmo justo, generalmente un depósito de tokens o una ventana deslizante, y explica sus límites claramente con un 429 y un reintento posterior. El cliente respeta esas señales y retrocede con nerviosismo. Comience con límites generosos por clave API, observe el uso real y ajuste solo donde sea necesario.

Preguntas frecuentes

sigue aprendiendo