For developers
Rate limits
Two layers, both with figures taken from the API’s own defaults, and what a 429 asks you to do.
Rate limits
There are two, and they are counted separately:
- Per calling address: 60 requests every 60 seconds by default, applied before your credential is even read. Exceeding it is
v1_rate_limited_address. It says nothing about your token: everything calling from that address shares the budget. - Per token: 120 requests every 60 seconds by default, counted once your token has been verified. Exceeding it is
v1_rate_limited_token. A second token in the same Business has its own budget, which is the clean way to separate a high-frequency catalogue sync from your order path.
Both answer 429 with a Retry-After header in seconds. Use that number. The two above are the shipped defaults and an operator may tune either, so Retry-After is the only figure that is always right.
Back off exponentially with jitter on a 429, and cap your retries. Retrying a write after a 429 is safe as long as you send the same Idempotency-Key, which is the second reason the header is mandatory.