Qué es un rate limit en una API y cómo aplicarlo

Una API comparte CPU, memoria, conexiones y servicios externos entre muchos clientes. Si un cliente envía solicitudes sin límite, puede ocupar la capacidad disponible y dejar a los demás esperando. Un rate limit convierte esa capacidad en una regla visible: durante una ventana, cada identidad puede hacer sólo cierta cantidad de pedidos.

También puede servirte: Qué es la idempotencia en una API y cómo evita duplicados

El límite no es una garantía de rendimiento. Sirve para repartir el acceso, controlar costos y absorber picos previsibles. Cloudflare lo presenta como una regla que cuenta solicitudes y aplica una acción cuando se supera el umbral; el equipo debe decidir qué identidad contar y qué respuesta ofrecer.

No es lo mismo limitar una IP que una cuenta, una clave o una combinación de ruta y método. Una red corporativa puede compartir IP entre cientos de personas, mientras que una clave puede aparecer en varios servidores. La dimensión elegida debe coincidir con el abuso o el recurso que se quiere proteger.

Una cuota suele expresar cuánto puede consumir un cliente en un período largo, como un día o un mes. Un rate limit controla la velocidad en una ventana corta, por ejemplo solicitudes por segundo o por minuto. Una cuenta puede tener cuota disponible y aun así recibir un rechazo temporal porque está enviando demasiado rápido.

Throttling describe la reducción o regulación de la velocidad cuando se alcanza una capacidad. AWS API Gateway aplica límites de ráfaga y de velocidad para controlar el flujo de solicitudes; esos valores se combinan con cuotas y con la capacidad real del backend. Llamar a todo “límite” sin separar estas capas vuelve difícil diagnosticar el rechazo.

La ventana puede ser fija, deslizante o implementarse con un token bucket. La fija es sencilla pero puede permitir dos ráfagas juntas en el borde de dos minutos. La deslizante reparte mejor el conteo. Token bucket permite una ráfaga acotada y luego una tasa sostenida, una decisión útil cuando el tráfico normal no llega de forma pareja.

Cuando la solicitud excede el límite, la API suele responder con HTTP 429 Too Many Requests. La respuesta debería indicar que el rechazo es temporal y, cuando se pueda calcular, enviar Retry-After con segundos o una fecha. El cliente puede mostrar un mensaje comprensible y guardar la causa sin exponer una clave secreta.

Los encabezados también pueden comunicar el límite, lo usado y el momento de reinicio. No existe un nombre universal que todas las plataformas implementen igual, por lo que el contrato debe documentar los campos que el cliente puede leer. Una respuesta consistente evita que cada integración adivine cuándo volver a intentar.

Un rate limit global no reemplaza la autorización. Un cliente autenticado puede estar autorizado a llamar a una ruta y aun así superar su velocidad permitida. La API debe comprobar identidad y permisos antes de decidir el límite, y separar los errores de credenciales, permisos y capacidad para que el cliente pueda actuar de forma distinta.

Reintentar inmediatamente después de un 429 repite el problema. GitHub recomienda respetar los encabezados y esperar antes de volver a pedir; el intervalo real depende de la señal que entregue la API. Si no hay una indicación, el cliente puede usar backoff exponencial con un máximo y un pequeño jitter aleatorio.

No todas las operaciones son seguras para repetir. Una lectura suele poder reintentarse, mientras que crear un pago o modificar un recurso necesita una clave de idempotencia o una comprobación del resultado anterior. La política debe identificar el método, el código recibido y si la acción puede generar efectos duplicados.

Los reintentos también deben tener un presupuesto. Definí cuántas veces se prueba, cuánto tiempo total puede esperar el usuario y qué alternativa queda cuando el límite persiste. Si muchos clientes comparten el mismo proceso, una cola interna o un limitador local puede coordinar los intentos antes de llegar al servidor.

Elegí la identidad, la ruta, el método y la ventana que realmente representan el recurso protegido. Medí solicitudes aceptadas, 429, latencia, tamaño de ráfagas y consumo por cliente. Probá tráfico normal, una ráfaga breve, varios clientes detrás de una IP y una recuperación después del reinicio de la ventana.

Documentá los límites en el contrato de la API e incluí ejemplos de Retry-After y de cada encabezado. El cliente debe saber si tiene que esperar, reducir la velocidad o pedir una cuota mayor. La documentación también debe aclarar si el límite es por usuario, aplicación, organización o endpoint.

Por último, alertá sobre un aumento de rechazos y revisá si el límite está protegiendo el backend o bloqueando clientes legítimos. Ajustar el número sin mirar el costo de una consulta puede ocultar la causa. Un rate limit útil hace predecible el acceso y deja evidencia para corregir capacidad, abuso o configuración.