> For the complete documentation index, see [llms.txt](https://api.shopwaive.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api.shopwaive.com/classic/reference/shopwaive-api-rate-limits.md).

# Shopwaive API rate limits

How many requests a second each part of the Shopwaive API takes, and what happens over the limit

To keep the platform stable and fair for everyone, the Shopwaive API limits how many requests it takes. Space your requests, cache what you read often, and retry responsibly.

***

## Limits by request

| Requests                                                                                           | Limit                                                         |
| -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| `GET`, `POST` and `PUT /api/customer`, `GET /api/actions`, `GET` and `POST /api/action/{actionid}` | 2 requests a second                                           |
| `DELETE /api/action/{actionid}`                                                                    | 20 requests a second                                          |
| Enterprise routes (below)                                                                          | 20 requests a second                                          |
| [Loyalty API](https://api.shopwaive.com/classic/reference/rest-api-documentation/loyalty-api.md)   | 20 requests a second for each key, with short bursts up to 40 |

The limits above are for each API key. On every request here but the Loyalty API, all the keys of one store together can send three times a key's limit, for example 6 requests a second to the requests limited to 2.

{% hint style="info" %}
**Tip:** If your application needs a higher limit, contact us at <support@shopwaive.com>.
{% endhint %}

## Over the limit

A request over the limit gets HTTP `429` and a `Retry-After` header with the seconds to wait:

{% code overflow="wrap" %}

```json
{
  "error": "Too many requests. Limit requests to avoid throttling, max of 2 requests per second. If needed, upgrade to the Enterprise rate plan by contacting sales@shopwaive.com "
}
```

{% endcode %}

Answers from the limited `/api/customer` and `/api/action` routes carry `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`. Use them to slow down before you reach the limit.

## Segment deposits

A `PUT /api/customer` (or `PUT /v2/api/customer`) with a `segment_query` gives the amount to every customer in a Shopify customer segment. It has its own rules:

* It is available on the Shopwaive Checkout plan. On another plan it returns HTTP `403` with the reason `plan_required`, and nothing is changed.
* It needs an `Idempotency-Key` header. Without one it returns HTTP `400` with the reason `idempotency_key_required`.
* A store can send one a minute. A second one within the minute returns HTTP `429` with the reason `bulk_too_soon` and a `Retry-After` header.
* A store can deposit to 10,000 rows a day (UTC), and each segment deposit counts as 1,000. Over that, the request returns HTTP `429` with the reason `bulk_daily_limit` and a `Retry-After` header to the next UTC day. To raise the limit, contact <support@shopwaive.com>.
* A retry with the same `Idempotency-Key` on the same day is not counted again.
* HTTP `503` with the reason `bulk_check_unavailable` means the request could not be checked, and nothing was scheduled. Retry in a minute with the same `Idempotency-Key`.

## Enterprise limit

With an enterprise rate plan, our team gives you a key for the `X-Shopwaive-API-Enterprise` header. Send it, and add **/v2** in front of the route. Three routes have an enterprise version:

* `GET /v2/api/customer/{customer_email}`
* `POST /v2/api/customer`
* `PUT /v2/api/customer`

For example, to set a balance with the enterprise limit, send `POST /v2/api/customer` in place of `POST /api/customer`, with both headers and the `Idempotency-Key` header, as for `POST /api/customer`.

### Header

<table><thead><tr><th width="313">key</th><th>value</th></tr></thead><tbody><tr><td>X-Shopwaive-Access-Token</td><td>Your Shopwaive API key, which starts with <code>swak_</code> (required)</td></tr><tr><td>X-Shopwaive-API-Enterprise</td><td>The enterprise key our team gives you (required)</td></tr></tbody></table>

***

## Avoiding rate limit errors

* Request only the data your app needs.
* Cache data that your app uses often.
* Spread your requests out in a queue.
* Catch errors. After a `429`, wait the seconds in `Retry-After` before you send the next request.
