---
title: "Rate limits"
description: "How calls are metered per token and per store, and what happens past a limit."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.sherpo.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Rate limits

## Per token, per store

Calls are metered per token, in each store on its own: a token reaching three stores may call each at its full rate. The `/v1/merchants` calls, which name no store, are counted per token on their own.

- **Rate.** Unless the token sets its own, a token may make 600 calls a minute on each store.
- **Quota.** A token may also carry a quota of calls a day or a month, counted in UTC.

You set both when you create a token, and can change them later, on the merchant app's **API tokens** page, which also shows each token's calls on the store you are in. See [authentication](/merchant-api/authentication#create-a-token).

A <a href="/merchant-api/reference/bulk/">`POST /bulk`</a> call counts once, whatever its items, and runs at most 50 items. See [bulk changes](/merchant-api/bulk).

## Past a limit

A call past a limit answers `429` with the problem type [`not_permitted`](/merchant-api/errors#not_permitted) and the reason `limit`. When the API knows when the limit lifts, the answer carries `Retry-After` in seconds: wait that long before calling again. Without it, back off and retry, with a growing wait and a bound on attempts.

```http
HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 12
```

A refused call does nothing, so retrying it is always safe. The [errors page](/merchant-api/errors#retrying) has a helper that waits as long as the API asks, up to a minute. A spent quota's `Retry-After` runs to the end of its day or month, so don't wait it out in a loop.

## New tokens from one network

Calls with a token the API hasn't accepted in the last few minutes are also limited per network: about 30 a minute from one address (an IPv6 address counted by its /64), and 300 across an IPv6 /48. Past either, they answer `429` with the reason `limit` for up to a minute. A token in steady use is usually let through, so this only slows down a client trying many tokens, or a burst of first calls from many clients behind one address.

## Staying within the limits

- Page with the largest `limit` a list takes rather than many small pages.
- Use [bulk changes](/merchant-api/bulk) for the operations that take them.
- Listen to [webhooks](/merchant-api/webhooks) instead of polling for changes.
- Give each job its own token, so one busy job doesn't spend another's rate.
- Keep [license checks](/merchant-api/guides/verify-licenses) on your server for a while instead of checking on every request your software makes: each check counts like any call.

Source: https://docs.sherpo.io/merchant-api/rate-limits/index.mdx
