Rate limits
Rate limits
Calls are counted a minute and a day at a time.
Example answer
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:
| 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):
| Name | Type | Description | Allowed values |
|---|---|---|---|
RateLimit-Limit | header | Calls the window allows. | — |
RateLimit-Remaining | header | Calls left in it. | — |
RateLimit-Reset | header | Seconds until it ends. | — |
Retry-After | header | On 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.
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.