Rate limiting
How the API throttles requests, the headers it returns, and how to back off on a 429.
The API is rate limited to keep it fast and fair for everyone. When you exceed a
limit, the request is rejected with HTTP 429 — read the response headers to
know your ceiling and when you can retry.
Reading your limit
Throttled responses carry the standard rate-limit headers. Read them instead of hard-coding a number, so your client adapts as limits change:
| Header | Description |
|---|---|
X-RateLimit-Limit | The maximum requests allowed in the current window. |
X-RateLimit-Remaining | How many requests you have left in this window. |
X-RateLimit-Reset | Unix timestamp when the window resets. |
Retry-After | Seconds to wait before retrying (present on a 429). |
Limits are applied per account (and per IP for unauthenticated requests). Some sensitive endpoints — bulk import/export, credential resets, order pricing — enforce their own tighter limits; each such endpoint notes it on its reference page.
A 429 response
When you go over, you get the standard error envelope with meta.code 429:
{
"meta": {
"code": 429,
"status": "error",
"message": "Too Many Requests"
},
"data": null
}Backing off
Honour Retry-After
On a 429, wait the number of seconds in Retry-After before retrying — do not
retry immediately in a tight loop, or you will stay throttled. If Retry-After
is absent, back off exponentially (e.g. 1s, 2s, 4s) with a small random jitter.
Practical guidance:
- Watch
X-RateLimit-Remaining. Slow down as it approaches zero rather than waiting for the429. - Page, don't hammer. Use pagination and reasonable
per_pagesizes instead of many rapid small requests. - Cache what rarely changes. Reference data (categories, products) does not need to be re-fetched on every operation.
Retry only idempotent requests
Retrying a GET is always safe. Before retrying a write, make sure repeating it
will not create a duplicate — retry only when you know the first attempt did not
take effect.