Rate limits

Requests are counted per API credential in a fixed 60-second window. The default allowance is 600 requests per minute — roughly ten per second.

The window is fixed, not sliding: the counter resets on the minute rather than trailing your last request. Two bursts either side of a reset both succeed, so pace against X-RateLimit-Remaining rather than assuming an even rate.

Limits are per key, so a noisy background job on one key does not starve your checkout traffic on another. Splitting workloads across keys is a supported way to isolate them.

Reading your budget

Every response carries the current state, so you never have to guess:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 573
X-RateLimit-Reset: 1755861420

X-RateLimit-Reset is a Unix timestamp in seconds — the moment the window rolls and your allowance is whole again.

When you exceed it

You get 429 with the code rate_limited, and a Retry-After header holding the seconds until the window resets.

{
  "code": "rate_limited",
  "message": "Too many requests. Retry after the window resets.",
  "request_id": "req_8f3c2b1a9d7e"
}

Wait until X-RateLimit-Reset, then continue. Retrying immediately just consumes the next window.

Staying under it

Back off exponentially. On a 429, sleep and retry with a widening delay plus a little randomness. Fleets that retry on a fixed interval re-synchronise into a thundering herd and hit the wall together.

Cache the catalog. Packages and countries change rarely. Pull them on a schedule and serve your own copy rather than calling per page view.

Cache your token. It lasts an hour. Fetching one per request wastes a large share of your budget on authentication.

Page with a sensible limit. The maximum is 200. Reading 1,000 records as five calls of 200 is far cheaper than twenty calls of 50.