---
title: Rate limiting and scope
slug: merchant-api/rate-limiting-and-scope
createdAt: 2021-10-01T12:04:02.000Z
---

# Best practices

Every API endpoint is subject to rate limiting. Several headers are included within every call's reponse to indicate rate-limiting status:

| **header name**                | **example** | **definition**                                                                 |
| ------------------------------ | ----------- | ------------------------------------------------------------------------------ |
| `RateLimit-Limit`              | 6           | Maximum available request in total<br />(lowest of two limits)                 |
| `RateLimit-Remaining`          | 5           | Number of remaining requests                                                   |
| `RateLimit-Reset`              | 12          | Specifies how long you must wait<br />before limits are reset, in seconds.     |
| `X-RateLimit-Limit-Hour`       | 50          | Maximum available request per hour                                             |
| `X-RateLimit-Limit-Minute`     | 6           | Maximum available request per minute                                           |
| `X-RateLimit-Remaining-Hour`   | 49          | Number of remaining requests<br />for the current hour                         |
| `X-RateLimit-Remaining-Minute` | 5           | Number of remaining requests<br />forthe current minute                        |
| `Retry-After`                  | 51          | Specifies how long you must wait<br />before making a new request, in seconds. |

When a limit is reached, the API returns an `HTTP 429` status code, with the following JSON body:

:::BlockQuote
\{ "message": "API rate limit exceeded" }
:::

We strongly recommend catching `HTTP 429` responses and parsing the **Retry-After&#x20;**&#x68;eader. You should then wait until the specified amount of time has passed before making additional calls.

:::hint{type="info"}
Please note that Neteven can decide to ban you from calling a certain endpoint should you exceed said limits too frequently.
:::

# Rate limits and scope per endpoint

Below is the list of all the endpoints available with the Merchant API and the corresponding required claims and rate limits.

All these limits are based on the `login` used, with the exception of the `/auth` endpoint, which uses the client's `IP address` as a criterion.
 <u>This is particularly important if you have a test environment using the same IP address</u> (grouped limits on the /auth call).

Please note that the rate limiting of each indiviual endpoint / method can be changed at Neteven's own discretion.&#x20;

| **endpoint**                                                        | **method** | **scope**                   | **rate limits**          |
| ------------------------------------------------------------------- | ---------- | --------------------------- | ------------------------ |
| /auth                                                               | `POST`     | `/`                         | 20/hour                  |
| /currencies                                                         | `GET`      | *(requires authentication)* | 10/hour                  |
| /languages                                                          | `GET`      | *(requires authentication)* | 10/hour                  |
| /conditions                                                         | `GET`      | *(requires authentication)* | 10/hour                  |
| /price-fields                                                       | `GET`      | *(requires authentication)* | 10/hour                  |
| /merchant/products/import-file                                      | `POST`     | `product_manager`           | 30/minute - 100/hour     |
| /merchant/products/imports/&#x7B;process-id}                        | `GET`      | `product_reader`            | 30/minute - 1000/hour    |
| /merchant/items/stocks                                              | `GET`      | `stock_reader`              | 30/minute  - 1000/hour   |
| /merchant/items/stocks                                              | `PATCH`    | `stock_manager`             | 150/minute - 5000/hour   |
| /merchant/items/prices                                              | `GET`      | `price_reader`              | 30/minute  - 1000/hour   |
| /merchant/items/prices                                              | `PATCH`    | `price_manager`             | 60/minute - 2000/hour    |
| /merchant/warehouses                                                | `GET`      | `warehouse_reader`          | 30/minute  - 100/hour    |
| /merchant/warehouses                                                | `POST`     | `warehouse_manager`         | 30/minute  - 100/hour    |
| /merchant/orders                                                    | `GET`      | `order_reader`              | 30/minute - 1000/hour    |
| /merchant/orders/new                                                | `GET`      | `order_reader`              | 60/minute - 2000/hour    |
| /merchant/orders/&#x7B;order-id}                                    | `GET`      | `order_reader`              | 60/minute - 2000/hour    |
| /merchant/orders/&#x7B;order-id}                                    | `PATCH`    | `order_manager`             | 150/minute - 5000/hour   |
| /merchant/orders/&#x7B;order-id}/lines/&#x7B;order-line-id}/ack     | `PATCH`    | `order_manager`             | 1200/minute - 40000/hour |
| /merchant/orders/&#x7B;order-id}/lines/&#x7B;order-line-id}/confirm | `PATCH`    | `order_manager`             | 300/minute - 10000/hour  |
| /merchant/orders/&#x7B;order-id}/lines/&#x7B;order-line-id}/cancel  | `PATCH`    | `order_manager`             | 300/minute - 10000/hour  |
| /merchant/orders/&#x7B;order-id}/lines/&#x7B;order-line-id}/ship    | `PATCH`    | `order_manager`             | 600/minute - 20000/hour  |
| /merchant/orders/&#x7B;order-id}/lines/&#x7B;order-line-id}/refund  | `PATCH`    | `order_manager`             | 600/minute - 20000/hour  |
| /merchant/orders/&#x7B;order-id}/lines/&#x7B;order-line-id}/status  | `GET`      | `order_reader`              | 30/minute - 1000/hour    |
| /merchant/orders/returns                                            | `GET`      | `order_reader`              | 30/minute - 200/hour     |