Errors, limits and retries

Handle a connector failure according to its layer: HTTP authentication, JSON-RPC framing or the tool’s reported result. An HTTP 200 does not by itself mean a store operation completed.

Find the layer that failed

Layer	What to inspect	Example
HTTP and authentication	Status, authentication challenge and whether a body is expected	HTTP 401 requires authentication; a notification’s empty HTTP 202 is normal.
JSON-RPC	The top-level `error` or `result`, and matching request `id`	`-32601` means the requested method is unknown.
Tool result	`result.isError` and the structured result	A valid tool call can return `not_allowed`.
Business operation	Actual proposal, execution and receipt state	A prepared or approved change has not necessarily completed.

Check these in order. A client that attempts to parse every response as a successful tool payload will misreport normal notifications and hide useful authentication or permission failures.

Tool failures

The connector returns these machine-readable tool codes. Read the accompanying message for the specific next step.

Code	Meaning and response
`not_allowed`	The current grant does not allow the capability. Inspect consent and `about_this_connection`.
`scope_missing`	A required provider permission is absent. Address the provider permission separately.
`store_disconnected`	The store link is unavailable. Reconnect through the supported flow.
`limit_reached`	A usage or rate allowance has been reached. Inspect the allowance and reset information.
`expired`	The relevant proposal or authority has expired. Prepare and review a current proposal.
`drift`	The reviewed source or proposal state changed. Review the new state.
`shopify_error`	The provider operation failed or could not be completed as requested. Read the result before retrying.

A tool failure is represented inside the JSON-RPC result. This example uses a fictional message; branch on the stable code, not its exact prose:

{
  "jsonrpc": "2.0",
  "id": 8,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "This connection does not allow the requested capability."
      }
    ],
    "structuredContent": {
      "error": {
        "code": "not_allowed",
        "message": "This connection does not allow the requested capability."
      }
    },
    "isError": true
  }
}

The client should preserve the code for handling and show an understandable next step to the user. Do not send the entire credential-bearing request to logs or to a model in an attempt to explain the error.

Protocol and authentication

HTTP 401 requires an authentication or reconnect step. Malformed JSON and invalid JSON-RPC requests are different from a valid tool call that returns a failure. Standard JSON-RPC framing errors include parse error -32700, invalid request -32600, unknown method -32601 and invalid parameters -32602. Tool results can carry isError; handle that field as well as the top-level JSON-RPC error. Keep the request ID so the client can associate a response with the correct request. An unknown tool and an unknown JSON-RPC method are separate mistakes. Use the names returned by tools/list, then supply arguments matching that tool’s schema. Rewriting an invalid call in a retry loop will not repair a stale schema unless the client re-discovers and validates the contract. Notifications have no request ID. The connector answers an accepted notification with HTTP 202 and an empty body. GET and DELETE on the MCP transport return HTTP 405; this connector does not require an event stream or session deletion as part of normal operation.

Limits

A JSON-RPC batch can contain at most 20 requests. Batching is a transport convenience, not a bulk-store-write permission. Connector rate controls and plan allowances are separate from the general BYOM subscription. Read the active allowance through the connection and account surfaces rather than treating a documentation figure as a permanent entitlement. An empty batch or a batch above the size limit is invalid. Keep a unique request ID for every call that expects a response and match results by that ID. A batch containing a set of requests does not make them an atomic transaction across Shopify records. Tools that list business records can have pagination and input limits. Use the returned schema and paging fields. When a long field is shortened in a list response, retrieve the specific record before using the missing text in a decision. Do not silently treat a truncated list as the entire catalogue. about_this_connection reports monthly read/write usage and reset dates. That context helps explain limit_reached; a lower-level provider limit or temporary rate restriction may still need its own recovery step. The account’s active allowance is authoritative, not an example number in a guide.

Retry safely

Back off read requests when a transient provider or rate condition warrants it. Do not retry revoked consent, invalid arguments or drift unchanged. For any uncertain consequential result, inspect the receipt and provider state first. A timeout may follow a successful provider change. Blind retries can duplicate effects.

Situation	Recovery
Temporary failure of a read	Retry a bounded number of times with backoff when the response supports doing so; surface the failure if it persists.
Invalid arguments or unknown method	Correct the implementation and validate against the current schema.
Expired or revoked authentication	Refresh or reconnect through the supported flow.
Missing consent or Shopify scope	Explain the missing permission and use the appropriate consent/provider setup path.
Expired proposal	Prepare a current proposal and obtain the required decision again.
Source drift	Show what changed and review a fresh proposal.
Uncertain write outcome	Stop automatic retries and inspect the actual receipt and provider record.

For example, a product-title update may have reached Shopify before the client lost its response. First establish whether that exact change happened. A successful read-back or receipt can resolve that uncertainty; a second mutation can make it worse. Do not manufacture an idempotency header or reuse an expired proposal token for a store write. Use the connector’s supported proposal and recovery flow; no arbitrary client-selected idempotency-key contract is documented here.

Versioning

Negotiate MCP at initialisation and use discovered schemas. Recheck tool discovery after reconnecting or changing consent; do not assume that a saved list remains the current contract.

Give support enough context

Keep the approximate time, client name/version, negotiated protocol version, request ID, tool or method name, status/error code and whether the request was a read or a proposed effect. Describe the observed result and what you expected. Exclude bearer tokens, refresh tokens, customer records and raw private payloads. That is enough to start diagnosing most integration failures without turning a support request into a data disclosure. Reviewed 2 October 2026.

​Find the layer that failed

​Tool failures

​Protocol and authentication

​Limits

​Retry safely

​Versioning

​Give support enough context

​Related guides