Rate Limit

El Rate Limit define cuántas peticiones puede realizar una integración en un intervalo de tiempo. Esta página documenta el límite de la API de Fidel, el comportamiento ante una petición rechazada y el patrón de reintentos recomendado.

¿Qué es el Rate Limit? ⏱️

Es el número máximo de peticiones que un cliente puede realizar a la API dentro de un intervalo de tiempo determinado. Superado ese máximo, la API deja de procesar las peticiones de ese cliente y responde con un código de error hasta que el consumo vuelva a estar dentro del límite.

¿Para qué sirve? 🛡️

1. Estabilidad del servicio. Acotar la frecuencia de las peticiones evita la sobrecarga de la plataforma y garantiza tiempos de respuesta consistentes para todas las integraciones.

2. Prevención de abusos y uso excesivo. Un proceso mal configurado —un bucle sin control, una sincronización total cada pocos segundos— degrada el servicio para el resto de los clientes. El límite acota ese impacto.

Algoritmo: leaky bucket 🪣

El control se implementa con un algoritmo de balde con goteo (leaky bucket).

Cada petición agrega una unidad al balde, que se vacía a una tasa constante. Mientras la frecuencia de peticiones sea menor o igual a la tasa de vaciado, el balde nunca se llena. Si la frecuencia la supera, el balde se desborda y las peticiones siguientes son rechazadas hasta que se libere capacidad.

Implicancias prácticas:

• Las ráfagas cortas están permitidas, siempre que el balde tenga tiempo de vaciarse después.
• Lo que se controla es la frecuencia sostenida, no una petición aislada.

Alcance: por IP y por endpoint 🌐

El límite se aplica por dirección IP de origen y de forma independiente por endpoint. Cada endpoint tiene su propio balde, de modo que un proceso intensivo sobre el catálogo no consume la capacidad disponible para registrar pedidos.

Respuesta al superar el límite 🚦

La API responde 429 Too Many Requests y no procesa la petición.

La petición rechazada no produce ningún efecto. Un 429 indica que la solicitud no llegó a ejecutarse, no que haya quedado parcialmente aplicada. Es seguro reintentar la misma llamada, incluso en endpoints de escritura: no genera registros duplicados.

Reintentos con backoff exponencial 🔁

Reintentar inmediatamente después de un 429 vuelve a llenar el balde y prolonga el bloqueo. El patrón correcto es esperar y duplicar el tiempo de espera en cada intento fallido.

async function pedirConReintentos(url, opciones, maxIntentos = 5) {
  let espera = 1000; // ms

  for (let intento = 1; intento <= maxIntentos; intento++) {
    const respuesta = await fetch(url, opciones);

    if (respuesta.status !== 429) return respuesta;

    // Si la API informa el tiempo de espera, tiene prioridad sobre el cálculo local
    const retryAfter = respuesta.headers.get('Retry-After');
    const esperaReal = retryAfter ? Number(retryAfter) * 1000 : espera;

    console.warn(`429 recibido. Reintento ${intento} en ${esperaReal} ms.`);
    await new Promise(r => setTimeout(r, esperaReal));

    espera *= 2; // 1s, 2s, 4s, 8s, 16s
  }

  throw new Error('Reintentos agotados por límite de peticiones.');
}

Buenas prácticas ✅

Cacheá el token de acceso. Es válido por 24 horas. Solicitar uno por consulta duplica el consumo sin ningún beneficio.

Usá páginas grandes. Una petición con pageSize=200 consume un cuarto de la cuota que cuatro peticiones con pageSize=50, y devuelve el mismo volumen de datos.

Filtrá del lado del servidor. Cada endpoint expone parámetros de búsqueda y filtrado. Utilizarlos es siempre preferible a traer el listado completo y descartar registros en el cliente.

Cacheá los datos de baja variabilidad. Rubros y listas de precio no cambian durante la jornada: consultalos una vez por proceso.

Escaloná los procesos masivos. Programá las sincronizaciones completas en horarios de baja actividad y con pausas entre lotes.

Sincronizá de forma incremental. Cuando el endpoint permita filtrar por fecha de modificación, procesá únicamente los registros modificados en lugar del universo completo.

X-API-KEY 🔑

Junto con el Rate Limit se incorpora el header X-API-KEY: un valor fijo que identifica a la integración y acompaña al token de acceso.

curl -X GET "{{URL_BASE}}/api/products" \
  -H "Authorization: Bearer AbC1dEf2GhI3..." \
  -H "account: TU_ACCOUNT" \
  -H "X-API-KEY: TU_API_KEY"

Todavía no es necesario enviarlo. Definí los headers como configuración de la integración para poder activarlo sin desplegar cambios.

Si tu caso de uso requiere un volumen superior al permitido, contactá a soporte antes de pasar a producción para evaluar alternativas de integración.