Skip to content

Errors

The tool errors and HTTP statuses the merchant MCP server answers, and what to do about each.

Updated

A call can fail in two ways. Most refusals are tool errors: the HTTP request succeeds and the result says what went wrong. A few are HTTP statuses, when the connection itself has to change. Each tool’s page under Tools has an Errors section listing what that tool may answer.

Tool errors

A tool error is a result with isError: true. Its text is a sentence followed by the code in parentheses, and its structuredContent holds:

  • code: one of the codes below.
  • context: what the refusal is about, an object that may be empty.
  • retry_after: seconds to wait, on a refusal for too many calls, when known.
  • transient: true when the call may simply be tried again: a read, or get_asset_url when fetching the file failed.
{
  "isError": true,
  "content": [{ "type": "text", "text": "The call clashes with the current state. (conflict)" }],
  "structuredContent": {
    "code": "conflict",
    "context": { "field": "status", "current": "published" }
  }
}

not_found

“Nothing matches the reference given.” A reference such as { "id": "..." } names nothing in the store. context names the kind of record and the ref given. Check the id, or list the records to find it.

not_entitled

“The resource is held back from this caller.” It is a Sherpo code the merchant tools don’t answer today. context names the kind and id held back.

not_permitted

“This caller may not make this call.” context.reason says why, and the text is the reason’s own sentence:

reason Text What to do
principal “This caller may not act on this resource.” The connection may not act on this record, the call isn’t open to connections at all, or an app connection no longer reaches the store’s business (the seller removed it from that business, or left it). list_merchants with that store tells them apart: an empty list means the connection no longer reaches that store (the seller removed that business from it or left it, or the store was never picked for it), so connect again. A connection made before connections could reach several businesses answers 401 once its seller leaves the business, and may answer this way with an empty list for a moment before. Otherwise, if your seat should allow it, ask a member of the business with full access.
plan “The store’s plan does not include this.” Upgrade the store’s plan.
limit “Too many calls; try again later.” Wait. context.retry_at is when, and retry_after the seconds until then. See Limits.
paused “New unlocks are not available right now.” The store grants no new access. This starts once the business has been over a plan limit (stores, members, customers or storage) for 7 days, or once a payment is 7 days past due. 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. Upgrade, get back under the limit or settle the payment. See Limits.
suspended “The store is not available right now.” The business is suspended: it has been over a plan limit for 14 days while paying, or its plan ended, or it has none. Most writes are refused until it upgrades, gets back under the limit or pays for a plan again.

Each store counts a connection’s calls on its own, so a limit on one store doesn’t hold back calls to another.

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

A revoked or expired connection, or a missing scope, is never a tool error: it is an HTTP status. There are two exceptions, both a tool error carrying only its text (see Sign-in and consent): an answer that was already streaming, and a connection reaching several businesses calling a tool on a business that lacks a scope the tool declares while another business it reaches holds it.

conflict

“The call clashes with the current state.” context.field names what clashes and, where it helps, context.current its current value. Publishing a product that is already published answers { "field": "status", "current": "published" }. A store at a count limit, such as its webhook endpoints, answers { "field": "items" }, usually with current, as in { "field": "items", "current": 20 }. An upload past the storage allowance answers { "field": "value", "current": <bytes in use> }. Read the record, then decide whether the call is still needed.

A write that names what it read (a from, a live, an expect order or a version) and no longer matches also names the argument and what it expected: context.path is the argument, as for invalid, and context.reason says what it takes, such as an attachment id sent where the body’s asset id belongs, or a body that changed since. The text adds both, and current when the conflict carries it:

{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "The call clashes with the current state. At [\"live\",\"id\"]: takes the live body's asset id, got its attachment id. Now 0f8c1d2e-.... (conflict)"
    }
  ],
  "structuredContent": {
    "code": "conflict",
    "context": {
      "field": "asset",
      "path": ["args", "live", "id"],
      "reason": "takes the live body's asset id, got its attachment id",
      "current": "0f8c1d2e-..."
    }
  }
}

A stale id reads not the live body's asset id: it changed since, or the id names another file: read the body again with read_body and send the asset.id it answers. current names a file only when the connection may read files.

invalid

“An argument is malformed.” context.path names the argument as a list of keys, starting with "args" when Sherpo refused it, and context.reason says what is wrong. The text adds both, as in At ["store"]: required.

A refused rich text also says where in the text:

  • offset: the character it stopped at.
  • name: the tag, attribute or style it names.
  • excerpt: the text around it.

A block refused for its props (an unknown type or prop, a missing prop, or a value outside its set) points at the prop and names block, the type of the block holding it, and expected, what it takes there; the text adds both. get_body_schema answers every kind of body’s blocks and props before a write. A quiz’s block holding a key its type doesn’t take is refused the same way, expected listing the keys it takes.

{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "An argument is malformed. At [\"text\"]: not an allowed tag (div). Near \"<p>a</p><div>b</div>\". (invalid)"
    }
  ],
  "structuredContent": {
    "code": "invalid",
    "context": {
      "path": ["args", "text"],
      "reason": "not an allowed tag",
      "offset": 8,
      "name": "div",
      "excerpt": "<p>a</p><div>b</div>"
    }
  }
}

Fix the argument and call again. The server answers invalid on its own too: at ["name"] for a tool that doesn’t exist (“no such tool”), at ["arguments"] for arguments that aren’t an object, and at ["store"] for a missing or wrong store.

internal and unavailable

“The call failed inside the service.” and “The service could not be reached.” The call failed inside Sherpo.

  • A read marked transient: true may be tried again.
  • A write is never marked transient. The one exception is get_asset_url: marked a write, a retry only hands out another link (a download is recorded as one more delivery), so it may always be called again, transient or not.
  • Most writes take no idempotency key, and two take one of their own (see Writes and retries). After a failed write, read the state back before trying again: the write may have landed.

client-fault

“The API failed before or after calling the service.” The MCP server failed around the call. This error’s structuredContent holds type: "client-fault" in place of a code, and:

  • reached_core: whether the call reached Sherpo.
  • core_answer: when it did, ok if Sherpo answered the call, or internal if Sherpo’s answer is not known: none came back, or the server failed while reading Sherpo’s refusal.
{ "type": "client-fault", "reached_core": true, "core_answer": "ok" }

It is never transient. When reached_core is false, nothing happened, and the call may be made again. ok means a write landed: don’t send it again. For bulk, ok means Sherpo ran the items, so read them back to see which landed. With any other value, read the state back before trying again, or send the same key again for the two writes that take one.

HTTP statuses

These answer the HTTP request itself, not a tool result.

Status When What to do
401 with WWW-Authenticate: Bearer error="invalid_token" The token is missing, wrong or expired, or the connection ended. An access token lasts up to 1 hour. Refresh the token. Only when the refresh fails with invalid_grant (the connection was revoked, expired or ended), or a refreshed token is refused again, connect again. See Sign-in and consent.
403 with WWW-Authenticate: Bearer error="insufficient_scope" The tool needs a scope the connection doesn’t hold. The connection stays. A connection’s scopes never change, so connect again and approve a set that holds the scope. See Scopes.
413 The request body is over 4 MiB. JSON-RPC error -32600, “The body is too large.” Send less in one call.
400 The body isn’t valid UTF-8 (-32700, “The body could not be read.”). On a 2025-era request, a body that isn’t JSON (-32700, “The body is not JSON.”) or a batch (-32600, “Batches are not supported.”). Send one JSON-RPC message per request.
405 with Allow: POST A GET or DELETE on a 2025-era request. JSON-RPC error -32000, “Method not allowed.” The server is stateless, with no stream to open and no session to end: use POST.

Both 401 and 403 name the server’s protected resource metadata in resource_metadata, so an MCP client can sign in again on its own. A client that already started reading the answer finds the reason as the result’s text too: “The connection was revoked or expired; connect again.” or “The connection lacks the scope this tool needs.”

The 429 answers of sign-in and registration are on Limits. Calling tools too often is a not_permitted tool error, never a 429.

Type to search…

↑↓ navigate↵ selectEsc close