Introducción

En el desarrollo de aplicaciones que interactúan con nuestra API, es importante comprender el concepto de Rate Limit y cómo afecta el flujo de solicitudes.

Esta guía explica de forma simple cómo funcionan los límites de uso de nuestra API y qué tener en cuenta al momento de realizar solicitudes.

¿Qué es el Rate Limit? ⏱️

El Rate Limit, o límite de velocidad, establece la cantidad de solicitudes que una integración puede realizar a la API dentro de un determinado período de tiempo.

El límite se aplica por token y puede variar entre distintas cuentas o integraciones.

Además, su funcionamiento es diferente según se utilicen endpoints v1 o v2.

¿Qué hace el Rate Limit? 🛡️

1. Garantiza la estabilidad del servicio: Limitar la frecuencia de las solicitudes ayuda a evitar sobrecargas y permite que cada petición sea procesada de manera eficiente.

2. Previene el uso excesivo: Controlar la cantidad de solicitudes permite distribuir los recursos de manera adecuada entre las distintas integraciones que utilizan la API.

Endpoints v2 ⚡

En los endpoints v2, la API informa el límite disponible a través de las cabeceras de cada respuesta.

El límite estándar es de 5 peticiones por segundo, y la cuota se renueva completa al inicio de cada segundo. Algunas integraciones pueden tener una cuota mayor asignada; en ese caso, las cabeceras reflejan el límite real del token utilizado.

Cabecera	Significado
`X-RateLimit-Limit`	Cantidad máxima de peticiones permitidas por segundo
`X-RateLimit-Remaining`	Cantidad de peticiones disponibles en el segundo en curso
`X-RateLimit-Reset`	Momento en que se renueva la cuota, expresado como Unix timestamp en segundos

Por ejemplo:

X-RateLimit-Limit: 5
X-RateLimit-Remaining: 4
X-RateLimit-Reset: 1787834007

En este ejemplo, el token tiene un límite de 5 peticiones por segundo y todavía dispone de 4 dentro del segundo en curso.

No es necesario conocer de antemano el límite asignado: la integración puede obtenerlo directamente desde las cabeceras de cada respuesta. Recomendamos leer X-RateLimit-Limit en lugar de fijar el valor en el código, de modo que la integración se adapte automáticamente si la cuota del token cambia.

¿Qué sucede si alcanzo el límite? ⚠️

Cuando se alcanza el límite disponible, la API responde con el código 429 Too Many Requests.

Además, se incluye la cabecera Retry-After, que indica cuántos segundos deben transcurrir antes de volver a realizar una solicitud.

Por ejemplo:

HTTP/2 429
X-RateLimit-Limit: 5
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1787834007
Retry-After: 1

La respuesta también incluye el detalle del error:

{
  "error": {
    "codigo": "LIMITE_PETICIONES_EXCEDIDO",
    "mensaje": "Límite de peticiones alcanzado. Reintentá en 1 segundos.",
    "reintentar_en_segundos": 1,
    "id_solicitud": "req_..."
  }
}

Al recibir una respuesta 429, es importante respetar el tiempo indicado en Retry-After antes de realizar un nuevo intento.

Endpoints v1 ⌛

Los endpoints v1 mantienen un esquema de límites diferente.

En este caso se aplican dos controles:

1. Tiempo mínimo entre solicitudes: Cada token tiene configurado un intervalo mínimo que debe respetarse entre una petición y la siguiente. Por ejemplo, un token puede tener establecido un intervalo de 5 segundos.

2. Cantidad máxima de solicitudes: Cuando este límite se encuentra activo para la cuenta, se permiten hasta 150 solicitudes cada 30 minutos.

Si se supera alguno de estos límites, la API responde con 429 Too Many Requests.

A diferencia de los endpoints v2, en v1 no se incluyen las cabeceras X-RateLimit-* ni Retry-After.

Buenas prácticas 💡

Para realizar un uso eficiente de la API:

Evitá realizar solicitudes innecesarias o repetidas.
En endpoints v2, espaciar las peticiones unos 200 ms entre sí permite mantener un flujo constante sin alcanzar el límite estándar.
En endpoints v2, consultá X-RateLimit-Remaining para conocer la cantidad de solicitudes disponibles, y X-RateLimit-Limit en lugar de fijar el límite en el código.
Si recibís un 429, esperá el tiempo indicado en Retry-After antes de volver a realizar la solicitud.
Tené en cuenta que el límite puede variar según el token utilizado.

Respetar estos límites permite mantener un servicio estable y eficiente para todas las integraciones.