---
title: "Limits"
description: "How many calls a connection may make, how large a call may be, and what a store's plan allows."
---

> 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.

# Limits

## Calls

Each store counts a connection's calls on its own. By default, a connection may make 600 calls a minute to each store.

The seller can change this for each business a connection reaches, on the Connections page in the merchant app, from the connection's "Edit limits in" action for that business. For a connection made before connections could reach several businesses, which is one of the seller's API tokens, they do it on the API tokens page, from the connection's "Edit limits" action. Either way they set:

- its own rate, in calls a minute;
- a quota of calls a day or a month, on top of the rate.

Minutes, days and months are counted in UTC.

Past a limit, a call is a tool error, not an HTTP `429`: `not_permitted` with `context.reason` set to `limit`, `context.retry_at` the time the window ends, and `retry_after` the seconds until then. The text reads "Too many calls; try again later. (not_permitted)".

```json
{
  "code": "not_permitted",
  "context": { "reason": "limit", "retry_at": "2026-11-03T14:06:00.000Z" },
  "retry_after": 23
}
```

Wait until `retry_at`, then call again. See [Errors](/merchant-mcp/errors#not_permitted).

## Sign-in and registration

A network is an IPv4 address or an IPv6 /64.

- Sign-in (`/authorize`): 30 a minute per network, and 300 a minute across an IPv6 /48. Past it, the browser shows "Too many sign-in attempts." with `429` and `Retry-After`.
- Registration (`/oauth/register`): 30 a minute per network, and 300 a minute across an IPv6 /48. On top of that, 20 an hour per network. Claude registers from Anthropic's published outbound addresses for everyone connecting it, so an address there may register 200 times an hour instead, with 2,000 an hour across all of them. Past any of them, `429` with the OAuth error `temporarily_unavailable` and "Too many registrations from this address; try again later." Past a per-minute limit, `Retry-After` is 60 seconds. Past the hourly one, `Retry-After` is sent when Sherpo knows when to try again.

A sign-in request is kept for 10 minutes: approve it within that time, or start again from your app. See [Sign-in and consent](/merchant-mcp/sign-in).

## Sizes

| What | Limit |
| - | - |
| A request body | 4 MiB. Past it, HTTP `413`. |
| A page of a list | 20 items by default on most lists. The most is on each tool's page: 100 for most lists, up to 1,000 for a few. |
| An `in` filter | 50 values. |
| A [`bulk`](/merchant-mcp/tools/bulk) call | 50 items. |
| A file handed back inside a result | 8 MiB. Past it, an `invalid` tool error. |
| An upload | 5,115 MiB a file. The bytes are sent within 15 minutes of [`create_upload`](/merchant-mcp/tools/create_upload). |
| An upload in the call | 2 MiB a file, with [`create_inline_upload`](/merchant-mcp/tools/create_inline_upload). |
| A rich text | 1 MiB of UTF-8, within its field's own limit. Sent as Markdown, 64 KiB. |
| Webhook endpoints | 20 a store. |
| Automations | 200 a store. Their runs are kept for 92 days. |
| API tokens | 100 live tokens a seller, across all their businesses. A connection made before connections could reach several businesses is one of them. |
| App connections | 100 live connections a seller, across all their businesses. Each connected app is one; the seller's API tokens don't count. |

A store at a count limit, such as its webhook endpoints or automations, answers `conflict` with `context.field` set to `items`, usually with `context.current` the count it holds.

## Plans

The merchant MCP server is on every plan, Lite included, and no plan sets a quota of calls.

A store's plan sets its other allowances: storage, transcription minutes, customers, pages, redirects, marketing emails and features. Read them, with what the store uses of each, with [`get_plan_usage`](/merchant-mcp/tools/get_plan_usage). Marketing emails answer their `allowance` with `used` set to null, since their use isn't reported there. [`get_quota`](/merchant-mcp/tools/get_quota) reads the store's storage use against its allowance.

An upload that would go past the storage allowance is a `conflict` with `context.field` set to `value` and `context.current` the bytes in use.

Once a business has been over any of its plan's limits (stores, members, customers or storage) for 7 days, or once a payment is 7 days past due, its stores answer `not_permitted` with `paused` in the context on anything that would grant new access. When auto-upgrade is on and the higher plan covers the overage in members, customers or storage, only an active Lite plan bought at checkout that renews, with no trial running and no change scheduled, may move to the higher plan instead of pausing. Any other plan, or a charge for the move that is refused, still pauses. This lasts until it upgrades, is back under the limit or settles the payment. After 14 days over a limit, or once its plan ends, or while it has none, the business is suspended: most reads still work, and most writes answer `not_permitted` with `suspended`. Suspended for being over a limit, it stays so until it upgrades or is back under the limit. A business is never deleted while its plan is paid.

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