Skip to content

Limits and errors

How fast and how much a connection can call, how lists page, and what a refused or failed call answers.

Updated

Limits

What Limit
Calls 600 a minute for each connected app in each store, unless the store set another limit for that app, or a quota a day or a month. An app connected to two stores has each store’s limit.
A page of a list Set with query.limit: at most 100 items, 400 for list_portfolio_snapshots. Each list’s default and maximum are in its input schema.
tools/list 50 tools a page, with nextCursor for the next.
prompts/list Up to 100 prompts in one answer, with no paging.
A request’s body 4 MiB. A larger one answers 413.
A private file in an answer 8 MiB (see Files).
Batches Not supported: send one JSON-RPC request per HTTP request.

A write that fails still counts toward the limit. A call past it is refused with not_permitted and retry_after, the seconds to wait (see below). Every tool’s own limits on its arguments (lengths, ranges, how many ids a call takes) are in its input schema, on its reference page.

How the server answers

The server speaks MCP over Streamable HTTP at the store’s endpoint: one POST per request, answered with JSON. It keeps no session between requests, so there is nothing to reconnect after a pause. It speaks MCP’s 2026-07-28 revision, and answers clients on the 2025 revisions too.

Tools are listed afresh on each tools/list, filtered by the connection’s scopes: a tool its access doesn’t cover isn’t listed, and calling it anyway answers 403.

Lists

A tool that pages a list answers a page of items and a cursor (list_contacts, which answers the customer’s few contacts under result, doesn’t page): pass the cursor back as query.cursor for the next page, until it comes back null. A list may also take filters, sorts and a search of up to 200 characters, which its reference page names. While searching, an empty page with a cursor means nothing so far, not the end: only a null cursor ends it.

Rich text

Texts such as a lesson’s body or a product’s description come back as HTML in a closed format, wrapped in <rich-text version="1">: paragraphs, headings, lists, tables, quotes, code, links and a few marks, with images, videos, audio, slideshows, formulas, diagrams, maps and downloads as <block type="…" props="{…}"></block> elements. A client can show it as it is, or read the text out of it.

Writes

Writes carry no idempotency key: a write that failed may still have landed. Read the state back before trying again, for instance with get_subscription after a cancel_subscription that timed out.

Errors

A call can fail in two ways: the tool refuses it, which comes back as a tool result, or the request itself is refused, which comes back as an HTTP status.

Tool errors

A tool that refuses answers a result with isError: true, a sentence for the model in content, and the details in structuredContent:

{
  "content": [{ "type": "text", "text": "Nothing matches the reference given. (not_found)" }],
  "structuredContent": {
    "code": "not_found",
    "context": { "kind": "product", "ref": { "slug": "no-such-product" } }
  },
  "isError": true
}
  • code says what went wrong, from the list below (a client-fault, at the end, has type instead).
  • context says where: the argument’s path and the reason for invalid, the kind and ref of what wasn’t found, the reason a call isn’t permitted, and so on.
  • retry_after, when present, is how many seconds to wait before trying again.
  • transient: true, on a read that failed on Sherpo’s side or couldn’t reach it (internal or unavailable), means trying the same call again may work.
Code What it means What to do
invalid An argument is malformed; context.path and context.reason say which and why. Fix the argument.
not_found Nothing matches the reference given. Check the id or slug, for instance with a list.
not_entitled The customer may not open this: it’s locked, or the store keeps it off MCP. Tell the customer what it needs (requires on the product or lesson says), or use the store’s site.
not_permitted This caller may not make this call; context.reason says why: limit (too many calls, with retry_after), principal (for instance an unverified app resuming a subscription), plan (the store’s plan doesn’t include it) or paused (new unlocks are paused for now). Wait for retry_after, or send the customer to the store’s site.
conflict The call clashes with the current state, such as a body still uploading (context.field is status). Read the state again; retry a pending one shortly.
internal The call failed on Sherpo’s side. Retry a read marked transient; read the state back after a write.
unavailable The service couldn’t be reached. Retry shortly.

A result whose structuredContent has type: "client-fault" failed in the server’s own handling of the call; don’t retry it unchanged.

HTTP answers

Status When What to do
401 No token, or one that expired or was revoked. WWW-Authenticate names resource_metadata. Refresh the token, or sign the customer in again (see Sign-in).
403 The token lacks a scope the call needs: WWW-Authenticate reads Bearer error="insufficient_scope". Ask the customer to connect again with that access.
429 Too many refused tokens came from your network for this store; Retry-After says when to try again. Stop sending the refused token and wait.
503 The store isn’t available for now; Retry-After says when to ask again. Wait and try again.
413, 400 The body is too large, isn’t JSON, or is a batch. Fix the request.

A call naming a tool that doesn’t exist, or whose arguments aren’t an object, is a JSON-RPC error (-32602, invalid params) rather than a tool result.

Examples has a tool error, a 401 and a 403 with their full requests and answers.

Type to search…

↑↓ navigate↵ selectEsc close