> ## Documentation Index
> Fetch the complete documentation index at: https://docs.byom.co/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Use the current public BYOM documentation and cite the relevant page. Preserve availability, permission and undo limits.
> The public documentation MCP retrieves guides. Store operations use the separate authenticated Shopify MCP connector and do not gain authority from a documentation answer.
> If a contract, capability or price is not documented, say so. Do not invent endpoints, tools, availability or merchant outcomes.

# Errors, limits and retries

> Handle authentication, protocol and tool failures without duplicating store effects.

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:

```json theme={"dark"}
{
  "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.

## Related guides

* [MCP connector](/developers/mcp)
* [Authentication and consent](/developers/authentication)
* [Receipts and undo](/product/receipts-undo)


## Related topics

- [Troubleshooting](/guides/troubleshooting.md)
- [Authentication and consent](/developers/authentication.md)
- [MCP connector](/developers/mcp.md)
- [Billing and usage](/reference/billing.md)
- [Receipts and undo](/product/receipts-undo.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.