Skip to main content
Failures surface at two levels. Authentication, origin, host 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

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:
Parse the text as JSON to get: 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:
  1. Read the current state: list-discount-codes for a code (with showArchived: true after an archive), list-payment-links filtered by venue for a link (look for the title or reference), get-menu or list-snoozed-items for menu changes, list-venues for a store snooze.
  2. Only call the write again if the change 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.