Límite de solicitudes

El límite de solicitudes protege a la API del abuso y garantiza un uso justo entre todos los tenants. Cada endpoint impone un límite sobre cuántas solicitudes puede hacer un mismo usuario dentro de una ventana de tiempo dada.

Estrategias

La API usa tres estrategias distintas de límite de solicitudes según el endpoint:

Ventana deslizante

Usada por la mayoría de los endpoints. Una ventana deslizante rastrea las solicitudes a lo largo de un período de tiempo móvil.

• Si el límite es de 10 solicitudes por 60 segundos, cada solicitud lleva una marca de tiempo.
• Cuando llega una nueva solicitud, el sistema cuenta cuántas solicitudes se hicieron en los últimos 60 segundos.
• Si el conteo excede el límite, la solicitud se rechaza con un estado 429.

Esto ofrece una experiencia más suave en comparación con las ventanas fijas — no hay un "abismo de reinicio" donde toda la capacidad se restaura de golpe.

Token bucket

Usado por el endpoint de telemetría para la ingesta de datos GPS. El token bucket permite ráfagas cortas mientras impone una tasa sostenida.

Parámetro	Global	Por IMEI
Capacidad del bucket	180 tokens	90 tokens
Tasa de recarga	30 tokens/seg	15 tokens/seg
Costo	1 token por 20 puntos GPS	1 token por 20 puntos GPS

En la práctica esto significa:

• Throughput sostenido: ~600 puntos GPS/segundo a nivel global, ~300 puntos/segundo por dispositivo
• Capacidad de ráfaga: hasta 3.600 puntos GPS en una sola solicitud (180 tokens × 20 puntos)
• Un lote de 100 puntos GPS cuesta 5 tokens. Si el bucket está vacío, la solicitud se rechaza hasta que se recarguen los tokens

Fuerza bruta en inicio de sesión

Usado exclusivamente por el endpoint de inicio de sesión para prevenir ataques de relleno de credenciales.

• Límite: 5 intentos por ventana de 30 segundos
• Duración del bloqueo: 60 segundos después de exceder el límite
• Durante el período de bloqueo, todos los intentos de inicio de sesión desde la misma fuente se rechazan de inmediato

peligro

Después de 5 intentos fallidos de inicio de sesión dentro de 30 segundos, tu cuenta se bloquea por 60 segundos. No hay forma de evitar este bloqueo — debés esperar a que expire.

Políticas de límite de solicitudes por grupo de endpoints

Grupo	Estrategia	Límite	Ventana
Login	login-bruteforce	5 intentos	ventana de 30s, bloqueo de 60s
Telemetría	token-bucket	capacidad 180	recarga 30/seg
Flota — Dispositivos	sliding-window	30 sol.	60 seg
Flota — Conductores	sliding-window	30 sol.	60 seg
Reportes — AVL	sliding-window	10 sol.	60 seg
Reportes — GT Analytics	sliding-window	10 sol.	60 seg
Reportes — GT Operations	sliding-window	10 sol.	60 seg
Reportes — General	sliding-window	10 sol.	60 seg
Reportes — CPM	sliding-window	10 sol.	60 seg
Reportes — Portal	sliding-window	10 sol.	60 seg
Cuentas	sliding-window	10 sol.	60 seg
Clientes	sliding-window	10 sol.	60 seg
Workflow (lectura)	sliding-window	30 sol.	60 seg
Workflow (escritura: start/cancel/complete/reassign)	sliding-window	10 sol.	60 seg
Kanban (lectura)	sliding-window	30 sol.	60 seg
Kanban (escritura)	sliding-window	10 sol.	60 seg
Portal de Proveedores (lectura)	sliding-window	30 sol.	60 seg
Portal de Proveedores (escritura)	sliding-window	10 sol.	60 seg

Encabezados de respuesta

Cada respuesta de la API incluye información del límite de solicitudes en los encabezados:

Encabezado	Descripción	Presente en
X-RateLimit-Limit	Máximo de solicitudes permitidas en la ventana actual	Todas las respuestas
X-RateLimit-Remaining	Solicitudes restantes en la ventana actual	Todas las respuestas
X-RateLimit-Reset	Marca de tiempo Unix (segundos) en la que se reinicia la ventana	Todas las respuestas
Retry-After	Segundos a esperar antes de reintentar	Solo respuestas 429

nota

El endpoint de inicio de sesión es la excepción: cuando devuelve un 429, envía solo el encabezado Retry-After y ningún encabezado X-RateLimit-*. Todos los demás endpoints incluyen X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset.

Leer los encabezados de forma proactiva

No esperes a un 429 para reaccionar — monitoreá X-RateLimit-Remaining en cada respuesta y regulá tus solicitudes antes de llegar al límite:

JavaScript

const response = await fetch(
  `https://${TENANT}/apidev/v1/fleet/devices?limit=25`,
  { headers }
);

const remaining = parseInt(response.headers.get('X-RateLimit-Remaining'), 10);
const resetAt = parseInt(response.headers.get('X-RateLimit-Reset'), 10);

if (remaining <= 2) {
  const waitMs = (resetAt - Math.floor(Date.now() / 1000)) * 1000;
  console.warn(`Rate limit almost exhausted. ${remaining} left. Pausing ${waitMs}ms...`);
  await new Promise((resolve) => setTimeout(resolve, waitMs));
}

Python

import time

response = requests.get(
    f"https://{TENANT}/apidev/v1/fleet/devices",
    headers=headers,
    params={"limit": 25},
)

remaining = int(response.headers.get("X-RateLimit-Remaining", 999))
reset_at = int(response.headers.get("X-RateLimit-Reset", 0))

if remaining <= 2:
    wait = max(0, reset_at - int(time.time()))
    print(f"Rate limit almost exhausted. {remaining} left. Pausing {wait}s...")
    time.sleep(wait)

Manejo de respuestas 429

Cuando recibís un 429 Too Many Requests, usá el encabezado Retry-After para esperar el tiempo exacto requerido. Para una implementación completa de backoff exponencial que maneja tanto errores 429 como 500, ver la Estrategia de reintentos en Manejo de errores.

Ejemplo rápido en línea:

# Check headers on any response
curl -s -D - \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $APIKEY" \
  -H "tenant: $TENANT" \
  "https://$TENANT/apidev/v1/fleet/devices?limit=5" \
  | grep -i "x-ratelimit\|retry-after"

# X-RateLimit-Limit: 30
# X-RateLimit-Remaining: 28
# X-RateLimit-Reset: 1743782520

Alcance y concurrencia

Los límites de solicitudes tienen alcance por tenant, por usuario. Reglas clave:

Pregunta	Respuesta
¿Distintos usuarios comparten un límite?	No. Cada usuario tiene límites independientes.
¿Puedo usar varias claves de API para evadir los límites?	No. Los límites están atados al usuario, no a la clave.
¿Puedo usar varias cuentas de usuario para paralelizar?	Técnicamente sí, pero esto se considera abuso y puede derivar en una regulación a nivel de tenant. Si necesitás mayor throughput, contactá a tu ejecutivo de cuenta para conversar un plan de límite de solicitudes a medida.
¿Las operaciones de lectura y escritura comparten un límite?	Depende del grupo. Para la mayoría de los grupos, GET y POST/PUT/DELETE comparten una ventana. Para Workflow, Kanban y Portal de Proveedores, las lecturas (30 sol./min) y escrituras (10 sol./min) se rastrean como ventanas separadas.