Rate limits

Each key has its own limit of requests a minute, so one busy system never slows another.

Limits

An admin sets each key’s limit on the API keys page: 60, 120, 300, 600, 1200 requests a minute, 120 unless chosen otherwise. Every request that gets past the key checks counts, whether it then succeeds or not. The minute starts with a key’s first request and resets when it ends.

Headers

HeaderMeaning
X-RateLimit-LimitThe key’s requests a minute.
X-RateLimit-RemainingHow many are left in this minute.
X-RateLimit-ResetWhen this minute ends, in seconds since 1 January 1970 (UTC).
Retry-AfterOn a 429 only: seconds to wait before trying again.

When you reach it

The request is refused with 429 and the code rate_limited. Wait for the seconds in Retry-After, then carry on. If you reach the limit often, ask an admin to raise it, or use webhooks instead of asking the API again and again whether something has changed.

async function eos(path, init = {}) {
  for (;;) {
    const res = await fetch(`https://eos.aveoevents.com/api/v1${path}`, {
      ...init,
      headers: { Authorization: `Bearer ${process.env.EOS_API_KEY}`, ...init.headers },
    });
    if (res.status !== 429) return res;
    const wait = Number(res.headers.get("Retry-After") ?? 1);
    await new Promise((r) => setTimeout(r, wait * 1000));
  }
}

Two more limits

  • Failed key checks. An address whose requests fail the key check 30 times in a minute (a wrong, revoked or expired key) gets 429 too_many_failures for a minute, whatever key it sends.
  • Checkout holds from web pages. With a publishable key, one visitor holds at most five open checkout sessions; the sixth gets 429 too_many_holds until one is completed, cancelled or expires.

Staying under it

  • Ask for 100 results a page when you read whole lists.
  • Use expand=ticket_types rather than one request per event.
  • Keep what you read for a short while, such as an event list for a minute, rather than asking on every page view.
  • Let webhooks tell you about orders and check-ins.