isError: true.
HTTP-Level
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 hasisError: true, a single text block and no structuredContent:
Arguments that fail a tool’s input schema (a wrong type, a value out of range, an unknown enum value, a malformed date or an offset-less write timestamp) never reach the tool. The MCP SDK answers them with an
isError: true result whose text is plain, not JSON, for example MCP error -32602: Input validation error: Invalid arguments for tool list-orders: dateBasis: Invalid option. Treat it like INVALID_INPUT.
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
Retrying
Reads (readOnlyHint: true) are safe to retry after TIMEOUT, UPSTREAM_UNAVAILABLE or INTERNAL_ERROR, with backoff.
Writes are different. create-discount-code, update-discount-code, create-payment-link, snooze-menu-items, snooze-menu-categories and snooze-venue are marked idempotentHint: false, and no write takes an idempotency key. A TIMEOUT is returned when the 30-second budget runs out, which can happen after the change has been committed — the code or link may already exist. Before retrying a write:
- Read the current state:
list-discount-codesfor a code (withshowArchived: trueafter an archive),list-payment-linksfiltered by venue for a link (look for the title or reference),get-menuorlist-snoozed-itemsfor menu changes,list-venuesfor a store snooze. - Only call the write again if the change is absent.
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 nostructuredContent, 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.