Rate limits
per token

Per-token limit

Each Personal Access Token has a limit of 100 requests per minute. The count is per token, not per store — three different tokens get three independent buckets.

When you exceed the limit, the API responds 429 Too Many Requests and rejects further requests from the same token until the window resets.

Handling 429

1. Stop requests from the affected token.
2. Wait 60 seconds, or use exponential backoff: 1 s, 2 s, 4 s, 8 s...
3. Retry with the same Idempotency-Key if it was a mutation.

JavaScript example

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;
}

Best practices to stay below the limit

• Cache read responses: don't poll the catalog every 10 seconds.
• Use webhooks for events: subscribe to order.completed instead of polling GET /external/orders.
• Multiple tokens for multiple workloads: separate buckets per integration.
• Don't retry 4xx: validation or scope rejections won't go away on retry.

Need more capacity?

If your legitimate use case sustains over 100 req/min, email us at hola@nuvlyx.com describing the pattern and we'll sort out a plan accordingly.