Storefront API rate limits

The Storefront API rate limits use a leaky bucket algorithm. The algorithm lets your app make an unlimited amount of requests in infrequent bursts over time.

After the limit is exceeded, all requests are throttled and return an {errors: [{ message: "Throttled" }]} error. Requests succeed again after enough points have accumulated in the bucket. Responses don't currently include information about the cost of the query or the state of the throttle.

Rate limits

The bucket's unit of measurement is the elapsed time in seconds that it takes to complete a request. The bucket size is 60 seconds, and this can't be exceeded at any given time or a throttling error is returned. The bucket empties at a leak rate of one per second.

The 60-second limit applies to the IP address of the buyer interacting with the app, rather than the ID of the shop where the app is installed. This means your app won't be throttled due to an increase in buyer traffic on a merchant's shop.

Every request to the Storefront API costs at least 0.5 seconds to run. After a request completes, the total elapsed time is calculated and subtracted from the bucket.

Bucket limit example

Suppose that client requests to an app only take 0.5 seconds or less. Each request would cost the minimum 0.5 seconds. In this scenario, it's possible for a client to make a maximum of 120 parallel requests while remaining within the 60 second bucket limit (120=60/0.5).

Recommendations to avoid throttling errors

Designing your app with best practices in mind is the best way to avoid throttling errors. For example, you can stagger API requests in a queue and do other processing tasks while waiting for the next queued job to run. Consider the following best practices when designing your app:

  • Include code that catches the errors object. If you ignore these errors and keep trying to make requests, then your app won't be able to gracefully recover.
  • Your code should stop making additional API requests until enough time has passed to retry. The recommended backoff time is 1000 ms.
  • Optimize your code to only get the data that your app requires.
  • Use caching for data that your app uses often.
  • Regulate the rate of your requests for smoother distribution.

Sign up for a Partner account to get started.

Sign up