Rate limits

Each API key may send 60 requests per minute. The count resets at the end of each 60-second window.

Headers

Once the key is recognised, every answer (errors included) carries:

RateLimit-Limit: 60
RateLimit-Remaining: 41
RateLimit-Reset: 18

• RateLimit-Limit: requests allowed per window.
• RateLimit-Remaining: requests left in this window.
• RateLimit-Reset: seconds until the window resets.
• They are missing on 401 unauthorized and 403 api_disabled, which are answered before the key is counted.

Over the limit

The answer is 429 rate_limited with a Retry-After header in seconds. Wait that long, then retry; with an Idempotency-Key, retry with the same one (a 429 is never stored).

async function call(url, init, attempts = 5) {
  for (let i = 0; i < attempts; i++) {
    const res = await fetch(url, init);
    if (res.status !== 429) return res;
    const wait = Number(res.headers.get("Retry-After") ?? "1");
    await new Promise((r) => setTimeout(r, wait * 1000));
  }
  throw new Error(`Still rate limited after ${attempts} attempts`);
}

Staying under it

• Use one key per system, so a busy kitchen screen and your accounting sync don't share one budget.
• Poll no faster than you need (every 5–10 seconds is plenty for a kitchen screen).
• Use limit=100 when you page through many orders.
• Watch RateLimit-Remaining and slow down before it reaches 0.

Next: Versioning & changelog →