Errors and retries

A call to Shop MCP can fail in three places, and each one looks different:

HTTP errors

Request errors

A request the server can’t accept gets HTTP 400 and a JSON-RPC error, and no tool runs. Fix the request before you send it again. For example:

The -32602 messages for arguments point to the field with a JSONPath, such as $.catalog.pagination.limit.

Tool errors

A tool that runs and fails still returns a result, with isError: true. There are two kinds.

The service answered with an error

The catalog, the merchant or Shop answered, and the error is in the document. structuredContent has ucp.status: "error" and messages that say what went wrong. Asking get_product for a product that doesn’t exist returns:

{
  "ucp": { "version": "2026-08-25", "status": "error" },
  "messages": [
    {
      "type": "error",
      "code": "not_found",
      "content": "Product not found: gid://shopify/p/doesnotexist000",
      "severity": "unrecoverable"
    }
  ]
}

Show the messages to the shopper, or act on them as Checkout status describes for carts and checkouts.

A checkout that needs the shopper to finish on the merchant’s page isn’t an error: its status is requires_escalation, and isError is false.

Shop MCP couldn’t get an answer

When the service didn’t send a usable answer, the result has no structuredContent. Its text says what happened, and _meta carries a code:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "isError": true,
    "content": [{ "type": "text", "text": "Shopify Catalog rate-limited search_catalog (HTTP 429). Retry after 30 s." }],
    "_meta": {
      "com.shopify/error": { "code": "rate_limited", "retry_after": 30 },
      "com.shopify/upstream_status": 429
    }
  }
}

The approval tools return their own error documents, and com.shopify/error.code repeats the document’s first message code, such as invalid_instrument.

Retries

Shop MCP never retries a call for you. Whether you can repeat one depends on what it does.

Reads

search_catalog, lookup_catalog, get_product, get_cart, get_checkout, search_orders and get_account change nothing, so you can repeat them. After rate_limited, wait for retry_after first. For search_orders, don’t keep retrying a throttled search.

get_approval isn’t a plain read, since it can issue a card. Call it again only after a successful pending result.

Creates and updates

Send a UUID as meta.idempotency-key with each create and update. After a timeout or an ambiguous_outcome:

1. If you have the resource’s ID, read it with get_cart or get_checkout. When that shows the result, you’re done.
2. Otherwise, repeat the exact same request with the same key.

A create without a key that failed before returning an ID can’t be repeated safely, because it may have worked. Tell the shopper and stop. Use a new key for each new operation.

Completing a checkout

Never send complete_checkout twice, even with the same key. After an uncertain result, call get_checkout: only completed with an order confirms the purchase. Anything else, or a failed read, means it isn’t confirmed. Tell the shopper, give them continue_url, and stop.

From the CLI

The CLI reports a failure in its error envelope. retryable is true only when no response came back and repeating can’t cause a second effect: always for a read, for another write only when the request wasn’t sent, and never for checkout complete or an approval write. The CLI reference covers the envelope and exit codes.