Errors

Failures surface at two levels. Authentication, origin and rate-limit problems are rejected before MCP, as plain HTTP responses. Everything that happens inside a tool call comes back as an MCP tool result with isError: true.

HTTP-Level

Status	Cause	Body
`401`	Missing or invalid credential	`WWW-Authenticate: Bearer realm="OAuth", resource_metadata="…"` header; start OAuth discovery
`403`	`Origin` header not on the allow-list	`{ "error": "Origin not allowed" }`
`429`	More than 60 requests in a minute for this user or key	`{ "error": "Rate limit exceeded" }` with `Retry-After` in seconds

These are outside the MCP envelope; an MCP client library typically raises them as transport errors.

Tool Errors

A failed tool call is a normal JSON-RPC success whose result has isError: true, a single text block and no structuredContent:

{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "{\"error\":{\"code\":\"INVALID_INPUT\",\"message\":\"Date range exceeds 90 days\",\"nextSteps\":[\"Split the range into shorter intervals.\"],\"retryable\":false}}"
    }
  ]
}

Parse the text as JSON to get:

Field	Meaning
`code`	One of the codes below. Stable; branch on this
`message`	Short, safe description. For `INVALID_INPUT` it names the problem; for other codes it is a fixed phrase
`nextSteps`	Instructions an agent can follow
`retryable`	Currently always `false` — see Retrying

Nothing else from the underlying failure is exposed: no stack traces, SQL, upstream responses or internal IDs. Every request is logged server-side with the x-request-id echoed on the HTTP response; quote it when contacting support.

Codes

Code	When	Typical fix
`INVALID_INPUT`	Schema violation, a date range over 90 days, an offset-less write timestamp, `period` combined with `from`/`to`, an account-wide stats query on a multi-currency account	Correct the arguments; `message` says what failed
`PERMISSION_DENIED`	The credential cannot act on this account	Check the key or token
`NOT_FOUND`	The venue, order, menu or link does not exist on this account — resources on other accounts look identical to non-existent ones	Call `list-venues` (or the relevant list tool) and check the ID
`CONFLICT`	State prevents the write, e.g. a discount code already used at that venue	Read the current state, then decide
`TIMEOUT`	The tool exceeded 30 seconds, or an upstream call timed out	Narrow the query. For a write, check state before retrying
`UPSTREAM_UNAVAILABLE`	A dependency (database, payments provider) could not be reached	Wait, then retry reads; check state before retrying writes
`INTERNAL_ERROR`	Anything unexpected	Retry reads once; email mcp@storekit.com with the request ID if it persists

Retrying

Reads (readOnlyHint: true) are safe to retry after TIMEOUT, UPSTREAM_UNAVAILABLE or INTERNAL_ERROR, with backoff. Writes are different. create-discount-code and create-payment-link are marked idempotentHint: false and have no idempotency key. A TIMEOUT is returned when the 30-second budget runs out, which can happen after the row has been committed — the code or link may already exist. Before retrying a write:

list-discount-codes and look for the code, or list-payment-links filtered by venue and look for the title/reference.
Only call the write again if it is absent.

Never retry writes automatically. This is why retryable is false on every code today: the server does not know whether your write landed, so it does not tell you to retry.

Validation Errors From Your Client

Because errors carry no structuredContent, spec-compliant clients (including the official TypeScript SDK) skip output-schema validation on them and surface the envelope. If your client instead reports a -32602 or “structured content does not match schema” error, it is validating the text against the tool’s outputSchema; read the text block directly.

Developers

Guides

Ordering Agents

Merchant MCP

Webhooks

HTTP-Level

Tool Errors

Codes

Retrying

Validation Errors From Your Client

​HTTP-Level

​Tool Errors

​Codes

​Retrying

​Validation Errors From Your Client

HTTP-Level

Tool Errors

Codes

Retrying

Validation Errors From Your Client