Skip to content

Limits

How many calls a connection may make, how large a call may be, and what a store's plan allows.

Updated

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

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

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.

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 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.
An upload in the call 2 MiB a file, with 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. Marketing emails answer their allowance with used set to null, since their use isn’t reported there. 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.

Type to search…

↑↓ navigate↵ selectEsc close