Rate limits

Each key has a bucket of requests that refills every second. Each store also has a daily allowance shared by all its keys, so one runaway script can't use up the store's whole allowance.

Every response tells you where the key stands:

RateLimit-Limit: 20
RateLimit-Remaining: 17
RateLimit-Reset: 0

• RateLimit-Limit: the bucket's size.
• RateLimit-Remaining: requests left right now.
• RateLimit-Reset: seconds until the next request is allowed when none are left.

A request over the limit gets 429 rate_limited with Retry-After in seconds. Wait that long, then retry.

Staying within limits

• Use webhooks instead of asking every few seconds whether anything changed.
• Sync changes, not everything: use updated_at_min (see Pagination and syncing).
• Use bigger pages: limit=250 reads five times as much per request as the default.
• Spread out bulk jobs, and slow down when RateLimit-Remaining gets low.