REST Admin API rate limits

The Shopify REST Admin API applies rate limits to the API requests that it receives. Every request is subject to throttling under the general limits. In addition, there are resource-based rate limits and throttles.

Limits are calculated using the leaky bucket algorithm. All requests that are made after rate limits have been exceeded are throttled and an HTTP 429 Too Many Requests error is returned. Requests succeed again after enough requests have emptied out of the bucket. You can see the current state of the throttle for a shop by using the rate limits header.

General API rate limits

The rate limits are designed to allow your app to make unlimited requests at a steady rate over time while also having the capacity to make infrequent bursts. The rate limits use a leaky bucket algorithm. The bucket size and leak rate properties determine the API's burst behavior and request rate.

The default settings are as follows:

  • Bucket size: 40
  • Leak rate: 2/second

If the bucket size is exceeded, then an HTTP 429 Too Many Requests error is returned. The bucket empties at a leak rate of two requests per second. To avoid being throttled, you can build your app to average two requests per second. The throttle is a pass or fail operation. If there is available capacity in your bucket, then the request is executed without queueing or processing delays. Otherwise, the request is throttled.

There is an additional rate limit for GET requests. When the value of the page parameter results in an offset of over 100,000 of the requested resource, a 429 Too Many Requests error is returned. For example, a request to GET /admin/collects.json?limit=250&page=401 would generate an offset of 100,250 (250 x 401 = 100,250) and return a 429 response.

Recommendations

Design your app with API rate limits in mind to best handle request limits and avoid 429 errors. To avoid rate limiting:

  • Stagger API requests in a queue and do other processing tasks while waiting for the next queued job to run.
  • Use the rate limits header to balance your request volume.

Handling exceeded rate limits

If your app is throttled, then it won't be able to make any more requests until enough time has passed and your bucket has capacity again. You can calculate this wait time manually using the bucket size and leak rate properties, or by using the Retry-After response header. Your app can also use a more general exponential backoff algorithm to complete the call at a later time.

Rate limits header

You can check how many requests you've already made using the Shopify X-Shopify-Shop-Api-Call-Limit header that was sent in response to your API request. This header lists how many requests you've made for a particular shop. For example:

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

In this example, 32 is the current request count and 40 is the bucket size. The request count decreases according to the leak rate over time. For example, if the header displays 39/40 requests, then after a wait period of ten seconds, the header displays 19/40 requests.

Retry-After header

When a request goes over a rate limit, a 429 Too Many Requests error and a Retry-After header are returned. The Retry-After header contains the number of seconds to wait until you can make a request again. Any request made before the wait time has elapsed is throttled.

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

Resource-based rate limits

The following endpoints have an additional throttle that takes effect once a shop has 50,000 variants. After this threshold is reached, no more than 1,000 new variants can be created per day.

If an app reaches API rate limits for a specific resource, then it receives a 429 Too Many Requests response, and a message that a throttle has been applied. The same recommendations also apply to resource-based limits.

Sign up for a Partner account to get started.

Sign up