Rate limits
por token

Límite por token

Cada Personal Access Token tiene un límite de 100 peticiones por minuto. El conteo es por token, no por tienda — si genera 3 tokens distintos, cada uno tiene su propio cubo de 100/min.

Cuando supera el límite, la API responde 429 Too Many Requests y rechaza nuevas peticiones del mismo token hasta que la ventana se reinicia.

Cómo manejar 429

1. Detenga las peticiones del token afectado.
2. Espere 60 segundos (ventana completa) o use backoff exponencial: 1 s, 2 s, 4 s, 8 s...
3. Reintente con la misma Idempotency-Key si era una mutación.

Ejemplo en JavaScript

async function call(url, opts = {}, attempt = 0) {
  const res = await fetch(url, opts);
  if (res.status === 429 && attempt < 5) {
    const wait = Math.pow(2, attempt) * 1000;
    await new Promise(r => setTimeout(r, wait));
    return call(url, opts, attempt + 1);
  }
  return res;
}

Buenas prácticas para no llegar al límite

• Cachee respuestas de lectura: si su bot consulta el catálogo cada 10 segundos, baje la frecuencia o cachee localmente.
• Use webhooks para eventos: en vez de pollear GET /external/orders esperando que aparezca un pedido, suscríbase a order.completed.
• Múltiples tokens para múltiples cargas: si tiene varios bots con propósitos distintos, dele a cada uno su propio token con sus propios scopes y su propio cubo.
• No reintente errores 4xx: rechazos por validación o falta de scope no se arreglan reintentando.

¿Necesita más capacidad?

Si su caso de uso legítimo supera 100 req/min de forma sostenida, escríbanos a hola@nuvlyx.com describiendo el patrón de uso y veremos un plan acorde.