Working with the API
Rate limits
Each store gets a number of requests per minute that depends on its plan. Over it, requests are refused with 429 until the window moves on.
Limits by plan
| Plan | Live keys | Test keys |
|---|---|---|
| Starter | 120 requests a minute | 60 a minute |
| Growth | 300 a minute | 60 a minute |
| Scale | 900 a minute | 120 a minute |
The limit is per store, shared by all of its keys: creating more keys doesn't buy more throughput. Live and test traffic are counted separately.
Every response carries X-RateLimit-Limit with the store's limit.
When you go over
You get 429 rate_limited and a Retry-After header with the number of seconds to wait. Requests refused this way did nothing, so they are safe to send again.
async function call(url, init, attempt = 0) {
const res = await fetch(url, init)
if (res.status === 429 && attempt < 5) {
const wait = Number(res.headers.get('Retry-After') ?? '10')
await new Promise((r) => setTimeout(r, wait * 1000))
return call(url, init, attempt + 1)
}
return res
}Staying well under
- Use webhooks instead of polling for changes.
- Sync with
updated_sinceandlimit=100, not by re-reading every object. - Webhook payloads contain the whole object: there's no need to fetch it again.
- Spread bulk jobs over time instead of firing them all at once.
Too many requests with a wrong key from one address are slowed down separately, to stop key guessing.
