Rate limits

The API uses a token bucket per store. The bucket holds ten tokens, each request consumes one, and two tokens refill per second. You can send a burst of ten requests, then sustain two requests per second.

Running requests from several servers does not increase the limit. Every request counts, including /status and requests that return 400 or 404.

Headers on a successful request

X-RateLimit-Limit: 10
X-RateLimit-Remaining: 7
X-RateLimit-Reset: 2

X-RateLimit-Remaining reports the available tokens. X-RateLimit-Reset reports the seconds until the bucket is full. Slow requests as the remaining count approaches zero.

When you go over

HTTP/1.1 429 Too Many Requests
Retry-After: 1

{ "statusCode": 429, "message": "Too many requests" }

Retry-After is the number of seconds until a token becomes available. Wait for this interval before retrying.

A request that returns 429 was not processed. You can safely retry a rate-limited order creation.

Staying under it

• Page in bulk. One request with limit=100 costs one token. Two with limit=50 cost two.
• Use webhooks instead of polling. Refetch the order that changed instead of listing every order whole list on a timer. See Webhooks.
• Cache your products. They change when you change them, and products_update tells you when.
• Coordinate your workers. Independent retries from parallel jobs can keep the bucket empty. Use a shared queue with low concurrency.
• Limit /status checks. Once a minute is enough to confirm that the API is available.

Rate-limited requests are recorded in your store's API request log with status 429, so the log shows when you hit the ceiling and on which route.