---
title: "Limits and errors"
description: "How fast and how much a connection can call, how lists page, and what a refused or failed call answers."
---

> 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 and errors

## 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](/customer-mcp/availability#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](/customer-mcp/tools).

## 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`:

```json
{
  "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](/customer-mcp/sign-in#for-developers)). |
| `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](/customer-mcp/examples#errors) has a tool error, a `401` and a `403` with their full requests and answers.

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