Rate limits

Rate limits

Calls are counted a minute and a day at a time.

Example answer

Past the limithttp
HTTP/1.1 429 Too Many RequestsRateLimit-Limit: 10RateLimit-Remaining: 0RateLimit-Reset: 23Retry-After: 23{  "code": "RATE_LIMITED",  "message": "Your plan allows 10 API calls a minute; try again in 23 seconds.",  "details": {    "fields": {},    "limit": 10,    "window": "minute",    "retryAfter": 23  },  "requestId": "18188559082372202519"}

Made-up values.

Calls are counted in two windows, a minute and a day, for the whole organisation: all its keys, personal ones too, share one count, so more keys give no more room. Reporting events has its own count, at the same figure a minute and none a day, so a shop reporting every sale never blocks its own link calls. An agency’s key counts on its own, at the same figures, so an agency’s work never uses up its client’s room. A list sent in one call (create a link) counts one call for each item; items past the limit are refused on their own, as RATE_LIMITED, and the rest are made.

The limits are the plan’s, as Pricing lists them:

API limits by plan
Plan Calls a minute Calls a day Event reports a minute
Free 10 a minute 500 a day 10 event reports a minute
Starter 30 a minute 2,000 a day 30 event reports a minute
Pro 120 a minute 10,000 a day 120 event reports a minute
Business 300 a minute 30,000 a day 300 event reports a minute

A window starts with the first call counted in it and ends a minute (or a day) later: it is not a clock minute or a calendar day.

Where you standPermalink

Every counted answer says where you stand in the window with the least room left (the one that refused, on a 429):

Rate-limit headers
NameTypeDescriptionAllowed values
RateLimit-LimitheaderCalls the window allows.—
RateLimit-RemainingheaderCalls left in it.—
RateLimit-ResetheaderSeconds until it ends.—
Retry-AfterheaderOn a 429 only: seconds to wait.—

Past the limit a call answers 429 RATE_LIMITED, its message naming the limit and the wait, and details carrying them for code: limit, window (minute or day) and retryAfter.

Backing offPermalink

Wait Retry-After seconds after a 429, then send the call again. Better, slow down before it: when RateLimit-Remaining reaches 0, wait RateLimit-Reset seconds.

Wait out the window before the limitjavascript
async function call(url, init) {  const res = await fetch(url, init);  if (res.status === 429) {    await sleep(Number(res.headers.get('Retry-After')) * 1000);    return call(url, init);  }  if (res.headers.get('RateLimit-Remaining') === '0') {    await sleep(Number(res.headers.get('RateLimit-Reset')) * 1000);  }  return res;}const sleep = (ms) => new Promise((done) => setTimeout(done, ms));

Common mistakesPermalink

  • Making more keys for more room: they share the organisation’s count.
  • Retrying a 429 at once, in a loop: each refused call still counts in the day’s window, so a tight loop spends the day’s room on refusals.
  • Spreading calls over a clock minute: the window starts at its first call, so wait for the reset the headers give.