Límites de uso

120 peticiones por minuto y clave por defecto.

El límite es por clave, no por organización ni por IP: cada integración tiene su propio cupo y una no puede agotarle el de otra. Si tienes una web de venta y un control de acceso, dale una clave a cada una.

Se puede subir por clave desde el panel. Si tu tráfico legítimo no cabe en 120, escríbenos con el caso y lo ajustamos: el número por defecto está pensado para que una integración con un bucle mal escrito encuentre freno, no para estorbar a nadie.

Cómo saber cuánto te queda

Toda respuesta lleva el estado del contador:

RateLimit-Limit: 120
RateLimit-Remaining: 87
RateLimit-Reset: 34

• RateLimit-Limit — tu tope por minuto.
• RateLimit-Remaining — cuántas te quedan en la ventana actual.
• RateLimit-Reset — segundos hasta que el contador vuelva a cero.

La ventana es fija, de un minuto: el contador se reinicia de golpe, no se desliza. Eso hace que RateLimit-Reset sea un dato exacto y no una estimación, así que puedes fiarte de él para programar la siguiente tanda.

Cuando lo superas

HTTP/1.1 429 Too Many Requests
Retry-After: 34

{ "error": "rate_limited" }

if (res.status === 429) {
  const segundos = Number(res.headers.get('Retry-After') ?? 1)
  await esperar(segundos * 1000)
  // y reintenta
}

Un 429 es siempre reintentable. No es un error de tu petición: es «ahora no».

Cómo no acercarte al límite

Casi todas las integraciones que rozan el límite lo hacen por una de estas cuatro razones. Las cuatro tienen arreglo:

Pides páginas de 25. El máximo es 100. Recorrer 1.000 pedidos son 40 peticiones con el valor por defecto y 10 con limit=100. Es la mejora más barata que existe.

Relees el catálogo entero cada vez. Usa updatedSince para traer solo lo que ha cambiado. Ver paginación y sincronización.

Preguntas en bucle si un pedido ya está pagado. Eso son los webhooks. Un order.paid te llega solo, en el momento, y te ahorra un sondeo por segundo por cada pedido abierto.

Llamas a la API desde cada visita de tu web. Si tu cartelera consulta /events cada vez que alguien entra en tu página, una noche buena te agota el cupo. Cachea el catálogo en tu backend —un minuto ya cambia todo— y refréscalo con updatedSince. La API dice Cache-Control: private, no-store porque no debe cachearse en un CDN compartido, no porque no puedas guardarla tú.

Qué no cuenta

• Las entregas de webhook no consumen tu cupo: las peticiones las hacemos nosotros hacia tu servidor.
• Una petición rechazada por autenticación (401 sin clave válida) no cuenta. Nadie puede agotarte el cupo mandando peticiones inválidas en tu nombre.
• Una petición que falla por otra razón después de autenticarse sí cuenta. El coste ya se ha incurrido, y si no contara, un cliente con un bucle roto no encontraría freno.

Si un pico es puntual

Una importación inicial, una migración, un volcado histórico: escríbenos antes y te subimos el límite de esa clave el rato que haga falta. Es más rápido que descubrirlo a base de 429 un domingo por la noche.