# Rate limits

To protect our platform against API misuse or overuse and ensure the system is available for all our users we adopt a rate-limiting strategy, differentiated by [environment](https://docs.commercelayer.io/core/api-specification#environments) (*test* or *live*), HTTP method, and types of resources involved.

{% hint style="danger" %}
IP addresses that exceed the following rates will be blocked until the frequency of the specific call drops below the allowed limit. Please note that the count on the number of requests **is never reset**: you must consider the time intervals as sliding time windows (that's why no `X-Ratelimit-Reset` header is [included in the response](#response-headers)).
{% endhint %}

{% hint style="success" %}
If you're using Commerce Layer [JS SDK](https://github.com/commercelayer/commercelayer-sdk) to interact with our Core API you can leverage the [SDK Utils](https://github.com/commercelayer/commercelayer-sdk-utils) library to execute several API calls to a resource endpoint in batch and make sure not to hit the current rate limits ([see example](https://github.com/commercelayer/commercelayer-sdk-utils?tab=readme-ov-file#executebatch)).
{% endhint %}

## Authentication endpoint

All the requests to the `/oauth/token` endpoint to get an access token to [authenticate](https://docs.commercelayer.io/core/authentication) your API calls are never cached and are subject to stricter rate limits, regardless of the environment:

| Environment | Max number of requests | Time window |
| ----------- | ---------------------- | ----------- |
| Live, Test  | **30**                 | **1 min**   |

## Other endpoints

All the [resources](https://app.gitbook.com/o/-Lfu_B3DKew-kvoEWzTk/s/RWJeylueWkzLadK710XZ/) endpoint can be grouped into two main classes depending on whether they could be cached or not (*cacheable* or *uncacheable*). Two kinds of rate limits are applied to the IP with which you perform the calls to the `/api/*` endpoints:

* **Average** — the number of requests is calculated considering the *sum* of the requests sent to *all* the resource endpoints of the specific class in the related time window (e.g. you cannot send 400 live reqs to the `/api/bundles` endpoint, 400 live reqs to the `/api/skus endpoint`, and 400 live reqs to the `/api/prices` endpoint, all within the same 1-min window — because it would result in a total of 1200 reqs / 1 min).
* **Burst** — the number of requests is calculated on *each* single resource endpoint of the specific class (e.g. you can send 25 test reqs to the `/api/addresses` endpoint, 25 test reqs to the `/api/orders` endpoint, and 25 test reqs to the `/api/line_items` endpoint, all within the same 10-sec window)

### Read requests

Read requests (performed via `GET`,  `HEAD`, or `OPTIONS` HTTP methods) are subject to different rate limits based on the type of resource.

#### Cacheable

Please find below the list of *cacheable* resources. Read requests to the related endpoints are subject to the following rate limits:

<table><thead><tr><th>Environment</th><th>Limit type</th><th width="222">Max number of requests</th><th>Time window</th></tr></thead><tbody><tr><td>Live</td><td><em>Average</em></td><td><strong>1000</strong> (to all endpoints)</td><td><strong>1 min</strong></td></tr><tr><td>Test</td><td><em>Avera</em>ge</td><td><strong>500</strong> (to all endpoints)</td><td><strong>1 min</strong></td></tr><tr><td>Live</td><td><em>Burst</em></td><td><strong>250</strong> (per endpoint)</td><td><strong>10 secs</strong></td></tr><tr><td>Test</td><td><em>Burst</em></td><td><strong>125</strong> (per endpoint)</td><td><strong>10 secs</strong></td></tr></tbody></table>

<details>

<summary>Cacheable resources list</summary>

* [Bundles](https://app.gitbook.com/s/RWJeylueWkzLadK710XZ/bundles) — `/api/bundles`
* [Imports](https://app.gitbook.com/s/RWJeylueWkzLadK710XZ/imports) — `/api/imports`
* [Markets](https://app.gitbook.com/s/RWJeylueWkzLadK710XZ/markets) — `/api/markets`
* [Prices](https://app.gitbook.com/s/RWJeylueWkzLadK710XZ/prices) — `/api/prices`
* [Price list](https://app.gitbook.com/s/RWJeylueWkzLadK710XZ/price_lists) — `/api/price_lists`
* [Promotions](https://app.gitbook.com/s/RWJeylueWkzLadK710XZ/promotions) — `/api/promotions`
* All types of promotions — `/api/*_promotions`
  * [Buy X pay Y promotions](https://app.gitbook.com/s/RWJeylueWkzLadK710XZ/buy_x_pay_y_promotions) — `/api/buy_x_pay_y_promotions`
  * [External promotions](https://app.gitbook.com/s/RWJeylueWkzLadK710XZ/external_promotions) — `/api/external_promotions`
  * [Fixed amount promotions](https://app.gitbook.com/s/RWJeylueWkzLadK710XZ/fixed_amount_promotions) — `/api/fixed_amount_promotions`
  * [Fixed price promotions](https://app.gitbook.com/s/RWJeylueWkzLadK710XZ/fixed_price_promotions) — `/api/fixed_price_promotions`
  * [Free gift promotions](https://app.gitbook.com/s/RWJeylueWkzLadK710XZ/free_gift_promotions) — `/api/free_gift_promotions`
  * [Free shipping promotions](https://app.gitbook.com/s/RWJeylueWkzLadK710XZ/free_shipping_promotions) — `/api/free_shipping_promotions`
  * [Percentage discount promotions](https://app.gitbook.com/s/RWJeylueWkzLadK710XZ/percentage_discount_promotions) — `/api/percentage_discount_promotions`
* [SKUs](https://app.gitbook.com/s/RWJeylueWkzLadK710XZ/skus) — `/api/skus`
* [SKU options](https://app.gitbook.com/s/RWJeylueWkzLadK710XZ/sku_options) — `/api/sku_options`
* [Stock items](https://app.gitbook.com/s/RWJeylueWkzLadK710XZ/stock_items) — `/api/stock_items`
* [Stock locations](https://app.gitbook.com/s/RWJeylueWkzLadK710XZ/stock_locations) — `/api/stock_locations`

</details>

#### Uncacheable

Read requests to all other endpoints (not listed [above](#cachable)) are subject to the following rate limits:

<table><thead><tr><th width="164">Environment</th><th>Limit type</th><th width="225">Max number of requests</th><th>Time window</th></tr></thead><tbody><tr><td>Live</td><td><em>Average</em></td><td><strong>200</strong> (to all endpoints)</td><td><strong>1 min</strong></td></tr><tr><td>Test</td><td><em>Average</em></td><td><strong>100</strong> (to all endpoints)</td><td><strong>1 min</strong></td></tr><tr><td>Live</td><td><em>Burst</em></td><td><strong>50</strong> (per endpoint)</td><td><strong>10 secs</strong></td></tr><tr><td>Test</td><td><em>Burst</em></td><td><strong>25</strong> (per endpoint)</td><td><strong>10 secs</strong></td></tr></tbody></table>

### Write requests

Write requests (performed via `POST`, `PUT`,  `PATCH`, or `DELETE` HTTP methods) to **any** endpoint (regardless of whether the related resource falls into the *cacheable* or *uncacheable* category) are subject to the following rate limits:

<table><thead><tr><th width="164">Environment</th><th>Limit type</th><th width="225">Max number of requests</th><th>Time window</th></tr></thead><tbody><tr><td>Live</td><td><em>Average</em></td><td><strong>200</strong> (to all endpoints)</td><td><strong>1 min</strong></td></tr><tr><td>Test</td><td><em>Average</em></td><td><strong>100</strong> (to all endpoints)</td><td><strong>1 min</strong></td></tr><tr><td>Live</td><td><em>Burst</em></td><td><strong>50</strong> (per endpoint)</td><td><strong>10 secs</strong></td></tr><tr><td>Test</td><td><em>Burst</em></td><td><strong>25</strong> (per endpoint)</td><td><strong>10 secs</strong></td></tr></tbody></table>

## Response headers

You can get additional information you can use to avoid getting HTTP `429 Too many requests` [errors](https://docs.commercelayer.io/core/handling-errors) or to understand why your calls are being blocked by inspecting some specific headers included in the response:

| Header                      | Description                                                                                             |
| --------------------------- | ------------------------------------------------------------------------------------------------------- |
| **`X-Ratelimit-Limit`**     | The maximum number of requests allowed in the sliding time window.                                      |
| **`X-Ratelimit-Interval`**  | The total duration of the sliding time window (in seconds).                                             |
| **`X-Ratelimit-Remaining`** | The number of allowed requests remaining in the current time window (`0` in case of HTTP `429` errors). |

{% hint style="info" %}
The information in the headers above (number of requests, time window duration, etc.) refers to the *Average* [limit type](#other-endpoints) only.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.commercelayer.io/core/rate-limits.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.