Limitación de Velocidad en APIs Explicada: Cómo los Servicios Controlan el Tráfico de Solicitudes

La limitación de velocidad en APIs es una técnica que controla cuántas solicitudes puede hacer un cliente a una API en un período de tiempo determinado. Cuando un cliente supera ese límite, el servidor rechaza las solicitudes adicionales hasta que se reinicia la ventana de tiempo. Es el mecanismo principal que utilizan los servicios para regular el flujo de solicitudes, gestionar cuotas y protegerse contra abusos o sobrecargas accidentales.

Por Qué Existe la Limitación de Velocidad

Una API sin limitación de velocidad es una invitación abierta al caos. Un único cliente con comportamiento anómalo, un bucle de reintentos defectuoso o un ataque de denegación de servicio deliberado puede consumir todos los recursos disponibles del servidor e inutilizar el servicio para todos. La limitación de velocidad resuelve varios problemas distintos simultáneamente:

• Prevención de DoS y DDoS: Limita el daño que una única fuente puede causar al inundar el servidor con tráfico.
• Uso justo: Evita que un usuario muy activo monopolice recursos y perjudique a otros clientes en infraestructura compartida.
• Control de costos: La computación en la nube, las consultas a bases de datos y las llamadas a servicios externos cuestan dinero. Los límites mantienen los gastos predecibles.
• Protección de API: Ralentiza los ataques de relleno de credenciales y el raspado automatizado que dependen de altos volúmenes de solicitudes.
• Cumplimiento de SLA: Los niveles de pago pueden aplicarse técnicamente en lugar de solo contractualmente.

Cómo Funciona: La Mecánica Fundamental

En su forma más simple, un limitador de velocidad se coloca frente a tu API y rastrea un contador para cada identidad de cliente. Esa identidad generalmente es una de las siguientes:

• Dirección IP (tosca, fácil de falsificar)
• Clave API u token OAuth (precisa, vinculada a una cuenta)
• ID de usuario (para endpoints autenticados)
• Una combinación, como IP más ruta del endpoint

Cada solicitud entrante incrementa el contador. Si el contador supera el límite configurado antes de que expire la ventana de tiempo, el servidor devuelve HTTP 429 Too Many Requests y la solicitud se descarta o se pone en cola. Cuando la ventana se reinicia, el contador se reinicia y el cliente puede enviar de nuevo.

Dónde vive ese contador importa mucho. Los contadores en memoria en un único servidor son rápidos pero fallan en el momento en que amplías horizontalmente. Los sistemas de producción casi siempre almacenan el estado del límite de velocidad en una caché compartida, más comúnmente Redis, para que cada nodo del clúster vea el mismo recuento.

Algoritmos Comunes de Limitación de Velocidad

El algoritmo que elijas determina cómo se maneja el tráfico con ráfagas. Cada uno tiene compensaciones reales.

El token bucket es el algoritmo más ampliamente implementado en APIs reales. GitHub, Stripe y AWS utilizan variantes de él porque acomoda naturalmente ráfagas cortas (un usuario haciendo clic en varias cosas rápidamente) sin permitir inundaciones sostenidas.

Encabezados HTTP de Limitación de Velocidad que Verás en la Práctica

Cuando una API aplica limitación de velocidad, comunica el estado actual a través de encabezados de respuesta. No existe un estándar universal único, pero dos convenciones dominan:

Convención heredada (utilizada por Twitter/X, GitHub v3 y muchos otros):

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 43
X-RateLimit-Reset: 1719878400

Estándar de borrador IETF (campos de encabezado RateLimit, draft-ietf-httpapi-ratelimit-headers):

RateLimit-Limit: 60
RateLimit-Remaining: 43
RateLimit-Reset: 17

La diferencia clave: el X-RateLimit-Reset heredado es una marca de tiempo Unix, mientras que la versión IETF es segundos hasta el reinicio. Siempre verifica la documentación de cualquier API que integres.

Cuando se alcanza el límite, el servidor también debe devolver un encabezado Retry-After que indique al cliente exactamente cuántos segundos esperar antes de intentar de nuevo. No todas las APIs lo envían, pero las bien diseñadas sí lo hacen.

Gestión de Cuotas vs. Limitación de Velocidad

Estos dos términos están relacionados pero no son idénticos, y confundirlos causa errores reales en la integración.

• Limitación de velocidad controla la velocidad de las solicitudes: 100 solicitudes por minuto, 10 solicitudes por segundo.
• Gestión de cuotas controla el volumen durante un período más largo: 10.000 solicitudes por día, 1 millón de llamadas de API por mes.

Una única API puede aplicar ambas simultáneamente. Google Maps Platform, por ejemplo, aplica límites de velocidad por segundo Y límites de cuota mensuales. Puedes estar bien dentro de tu cuota mensual pero aún así ser limitado por enviar 50 solicitudes en un segundo. Alcanzar la cuota mensual devuelve un código de error diferente (a menudo 403 con un mensaje de cuota excedida) que alcanzar el límite de velocidad por segundo (429).

Cómo Manejar 429 Demasiadas Solicitudes en Tu Código

Recibir un429 no es un error fatal. Es la API diciéndote que ralentices. La respuesta correcta es un retroceso exponencial con jitter.

Aquí hay un ejemplo mínimo en Python:

import time
import random
import requests

def call_with_backoff(url, headers, max_retries=5):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)
        if response.status_code == 429:
            retry_after = int(response.headers.get("Retry-After", 2 ** attempt))
            jitter = random.uniform(0, 1)
            time.sleep(retry_after + jitter)
            continue
        response.raise_for_status()
        return response
    raise Exception("Max retries exceeded")

Puntos clave en este patrón:

• Lee Retry-After primero. Si la API lo proporciona, úsalo en lugar de adivinar.
• Añade jitter aleatorio para que múltiples clientes no reintentan exactamente en el mismo momento (el problema del "rebaño atronador").
• Limita el número de reintentos. Un bucle de reintento infinito es en sí mismo una forma de abuso.
• Registra las respuestas 429. La limitación de velocidad frecuente es una señal de que necesitas cachear resultados, agrupar solicitudes o mejorar tu plan.

La entrada de MDN Web Docs para HTTP 429 tiene una referencia concisa para la semántica del código de estado si quieres el detalle a nivel de especificación.

Ejemplos Reales de Limitación de Velocidad

Ver cómo implementan esto las APIs principales hace los conceptos concretos:

Mejores Prácticas para Consumidores y Proveedores de APIs

Ya sea que estés construyendo una API o consumiendo una, los mismos principios se aplican en ambos lados de la barrera.

Si estás consumiendo una API:

• Cachea respuestas agresivamente. La solicitud más barata es la que nunca envías.
• Agrupa solicitudes dondequiera que la API lo permita (por ejemplo, obtén 100 registros en una llamada en lugar de 100 llamadas individuales).
• Utiliza webhooks o eventos enviados por el servidor en lugar de polling cuando la API los ofrece.
• Monitorea tu encabezado X-RateLimit-Remaining de forma proactiva, no solo cuando alcances 429.
• Implementa circuit breakers en servicios de larga duración para que una API limitada no se convierta en un fallo de aplicación completo.

Si estás construyendo una API:

• Aplica límites a nivel de puerta de API (Kong, AWS API Gateway, Nginx), no dentro de cada microservicio.
• Diferencia los límites por nivel: usuarios gratuitos obtienen 100 RPM, usuarios pagos obtienen 1.000 RPM.
• Siempre devuelve Retry-After en respuestas 429. Los clientes que lo respetan se desactivarán limpiamente.
• Registra eventos de límite de velocidad. Un cliente que constantemente alcanza límites tiene un error o es un actor malicioso.
• Documenta tus límites claramente. Los límites no documentados son una pesadilla de soporte.

Configura el Control de Tráfico de Tu Servidor Sin Escribir Código

Gestionar la limitación de velocidad de API y el control de tráfico a menudo comienza en la capa de configuración del servidor. DevToolBox ofrece a los desarrolladores herramientas gratuitas basadas en navegador para generar, probar y copiar configuraciones de servidor al instante, para que dediques menos tiempo a código repetitivo y más tiempo a tu lógica de API real.

Prueba Nuestras Herramientas Gratuitas →