API rate limits

BigCommerce aims to provide outstanding platform reliability. To ensure reliability, we implement safeguards in the form of rate limits for our REST APIs.

These rate limits enhance quality for merchants by regulating excessive API calls. In this document, we provide information on rate limits along with some best practices to put in place.

How limits work

Each API request consumes one quota unit. The system rejects later requests once it reaches the quota. This continues until the quota is refreshed after the reset interval.

All apps accessing the store share the store's quota. This prevents a single app from using the entire quota. The available quota for an app adjusts as other clients make or stop requests.

Rate limits by plan type

Apps using OAuth are rate-limited based on a quota that's refreshed every 30 seconds. The maximum quota varies by store plan and requested resources.

Unlimited rate plan

The Unlimited Rate Plan is for some BigCommerce Enterprise clients. It has no request rate limits. But, it may face limits from physical infrastructure. These limits may cap the maximum request throughput for a resource.

For more on resource constraints, see object-related limits (Help Center) (opens in a new tab).

Best practices

Manage API rate limits by following these crucial guidelines for success.

Process rate limit HTTP 429 status code accurately, distribute request loads evenly, store results, and repeat requests strategically to boost app performance and prevent outages.

Handle rate limit status codes

API rate limits regulate the amount of calls made to your app. You can use the API's response HTTP headers to find more information about your current rate limit status:

X-Rate-Limit-Time-Window-Ms: 30000
X-Rate-Limit-Time-Reset-Ms: 15000
X-Rate-Limit-Requests-Quota: 150
X-Rate-Limit-Requests-Left: 35

Distribute the load

To avoid spikes in API requests and ensure efficient use of your quota, spread out your API calls over time. The practice helps prevent hitting rate limits by balancing the number of requests sent in a given time frame.

You can use strategies such as using asynchronous processes, batching requests, and using a queue. They will help you distribute the load evenly. You can also keep a smooth request rate by adjusting the rate based on the API response headers.

Caching results

Cache frequent results to reduce API calls.

Retry requests responsibly

To retry requests responsibly when using the BigCommerce API, follow these steps:

1. Monitor for 429 Responses: When you receive a 429: Too Many Requests response, it indicates that you've hit the rate limit.

2. Check the Retry-After Header: Use the X-Rate-Limit-Time-Reset-Ms header to determine how long to wait before retrying. This header provides the time in milliseconds until your quota resets.

3. Pause Before Retrying: Implement a delay in your code based on the X-Rate-Limit-Time-Reset-Ms value. For example, in PHP:

 $milliseconds = $response->getHeader("X-Rate-Limit-Time-Reset-Ms");
 usleep($milliseconds * 1000);

Seeing a 429 response?

If you encounter a 429 response without the API HTTP headers, this is an indication that the platform experiences high load due to excessive traffic on a particular store and the request may be retried at another time.

Here's an example of what a 429 response looks like:

 HTTP/1.1 429 Too Many Requests
 Date: Mon, 03 Feb 2022 20:36:00 GMT
 Content-Type: application/json
 X-Rate-Limit-Time-Window-Ms: 30000
 X-Rate-Limit-Time-Reset-Ms: 15000
 X-Rate-Limit-Requests-Quota: 150
 X-Rate-Limit-Requests-Left: 35

Continue to reduce the risk of an app outage by slowing down the amount of calls being made. This will reduce any strain on performance. For more details on response headers, see About Our API.

If retries continue to hit rate limits, gradually increase the wait time to avoid overwhelming the server.

By following these steps, you can ensure your requests are retried responsibly on the BigCommerce platform.

Resources

Related articles

• Platform limits - Store limits (opens in a new tab) (BigCommerce Knowledge Base)
• About our APIs - Response headers

Additional resources

• BigCommerce: Incorporated terms - API terms (opens in a new tab) (BigCommerce terms of service)