Skip to main content

Rate limits

Shoplazza API rate limits​

All Shoplazza APIs are rate-limited. The REST Admin API uses request-based limits: each request counts equally, regardless of how much data it returns.

The REST Admin API enforces limits across two dimensions:

  • App/store: each app and store pair has an independent limit.
  • Store: each store has an independent limit across requests.

For example: Each request is counted against both dimensions. For example, when App A calls Store 1, the request consumes capacity from the App A and Store 1 bucket, and also from the Store 1 bucket. The request succeeds only when both buckets have capacity.

Current bucket stateResult
App A + Store 1 is 39/40, and Store 1 is 79/80The request can run. After it is counted, the buckets become 40/40 and 80/80.
App A + Store 1 is 40/40, and Store 1 is 10/80The request is throttled because the app/store bucket is full.
App A + Store 1 is 10/40, and Store 1 is 80/80The request is throttled because the store bucket is full.

The default settings for the app/store dimension are:

  • Bucket size: 40 requests per app/store
  • Leak rate: 2 requests per second

The default settings for the store dimension are:

  • Bucket size: 80 requests per store
  • Leak rate: 20 requests per second

To avoid being throttled, follow these practices on the client side:

  • Keep a separate request queue for each store. This prevents a burst for one store from delaying calls to another store.
  • Limit the dispatch rate for each app/store pair to stay under the app/store leak rate.
  • Track the combined request volume for each store so all apps or workers calling the same store stay under the store leak rate.
  • Monitor the X-Shoplazza-Shop-Api-Call-Limit header on each response. When the value gets close to the bucket size, slow down before the bucket is full.
  • Cache responses you can reuse, especially repeated reads for the same resource.
  • When you receive a 429, pause the affected queue and read the Retry-After header. Resume requests after the number of seconds it specifies.

The leaky bucket algorithm​

All Shoplazza APIs manage requests with a leaky bucket algorithm. This lets your app make bursts of requests over time, as long as it doesn't overflow the bucket. The metaphor works as follows:

  • Each app has access to a “bucket” that holds a fixed number of “marbles” (for example, 40).
  • Each API request tosses one marble into the bucket.
  • The bucket leaks at a steady rate (for example, 2 marbles per second), freeing up space over time.
  • If the bucket is full, requests fail with an error until the bucket leaks enough to make room.

Rate limit headers​

Use the X-Shoplazza-Shop-Api-Call-Limit header returned with each API response to see how many requests you’ve made against a store.

X-Shoplazza-Shop-Api-Call-Limit: 32/40

  • 32: The current number of marbles in the bucket.
  • 40: The maximum bucket size.

The count leaks down over time. For example, if the header shows 39/40 and you stop sending requests, after ten seconds it may show 19/40.

The Retry-After header specifies the number of seconds to wait before retrying after a 429 Too Many Requests response.

Handling 429 responses​

When a request exceeds the rate limit, Shoplazza returns a 429 Too Many Requests error along with a Retry-After header. Wait for the specified number of seconds before retrying. Any request made during this period is throttled.

X-Shoplazza-Shop-Api-Call-Limit: 40/40
Retry-After: 2.0