Checkout MCP errors
Checkout MCP distinguishes between protocol errors and business outcomes.
- Protocol errors prevent Shopify from processing the request. They're returned as a top-level JSON-RPC
error. - Business outcomes are returned after Shopify processes the request. They're returned as a JSON-RPC
resultwithstructuredContentand amessagesarray.
Anchor to Protocol errorsProtocol errors
Protocol errors are returned when a request can't be authenticated, authorized, negotiated, parsed, or routed to the requested tool. The response doesn't include a checkout resource.
Discovery and capability-negotiation failures use the JSON-RPC error envelope. Shopify returns -32001 for UCP discovery failures and can include a more specific code in error.data.code, such as profile_unreachable or version_unsupported.
Retry protocol errors only when the failure is temporary, such as rate limiting or service unavailability. When Shopify returns an HTTP Retry-After header, wait for that duration before retrying. For lifecycle-changing requests, include an idempotency-key before retrying.
Anchor to Business outcomesBusiness outcomes
Business outcomes are returned as a successful JSON-RPC result. The request was processed, but Shopify might return either a Checkout with messages or an ErrorResponse.
Anchor to Checkout returned with messagesCheckout returned with messages
Use the checkout's status and messages together to decide whether to update the checkout, complete it, or hand off to the buyer.
Anchor to Checkout not createdCheckout not created
An ErrorResponse is returned when Shopify processes the request but can't create or return a checkout. For example, this can happen when the requested merchandise can't be added to a checkout. Inspect ucp.status, messages, and continue_url instead of checkout fields.
Always inspect result.structuredContent.ucp.status and result.structuredContent.messages. When a Checkout response is returned, also inspect result.structuredContent.status. Some warnings can be returned alongside a checkout that can continue, while some errors require either an update_checkout call or buyer handoff through continue_url.
Anchor to Message fieldsMessage fields
Checkout messages use the following fields:
| Field | Description |
|---|---|
type | Message type. Usually error, warning, or info. |
code | Machine-readable outcome code. Use the code with severity, status, and continue_url before branching in your agent flow. |
severity | The recommended recovery path. See Severity values. |
content | Human-readable message that can help explain the issue. |
content_type | Message format. Usually plain; can be markdown. |
path | JSONPath-style pointer to the affected request or checkout field, when available. |
Anchor to Severity valuesSeverity values
| Severity | Meaning | Recommended action |
|---|---|---|
recoverable | The agent can fix the checkout through API updates. | Prompt for the missing or corrected value, then call update_checkout. |
requires_buyer_input | The buyer must provide information that isn't available through the API flow. | Hand off through continue_url. |
requires_buyer_review | The buyer must review or approve something in the merchant checkout. | Hand off through continue_url. |
unrecoverable | The checkout can't continue from the current state. | Start a new cart or checkout, or show the buyer an alternative. |
When messages include requires_buyer_input or requires_buyer_review, the checkout status can be requires_escalation. Use continue_url to send the buyer to the merchant checkout.
Anchor to Error code behaviorError code behavior
This is not an exhaustive list. For most integrations, branch first on severity, checkout status, and the presence of continue_url. Branch on code only for codes your integration explicitly handles.
Anchor to Common handling codesCommon handling codes
| Code | Meaning | Recommended action |
|---|---|---|
out_of_stock | The requested item can't be fulfilled in the requested quantity. | Refresh product data, adjust quantity, or suggest alternatives. |
item_unavailable | The requested item can't be purchased in the current checkout context. | Remove or replace the item, then create or update the checkout. |
address_undeliverable | Shopify can't find a delivery option for the destination. | Ask the buyer for a different address or remove items that can't ship. |
payment_failed | The submitted payment method or payment configuration can't be used. | Ask for a different payment path or hand off through continue_url. |
redirect_to_checkout_required | The buyer must complete an action in the merchant checkout. | Hand off through continue_url. |
For item_unavailable, Shopify returns generic localized content when possible, such as Item cannot be purchased. Other codes can include content from checkout validation. Treat content as explanatory text, not as a stable identifier.
Anchor to Tool and submission codesTool and submission codes
Some codes describe the tool call or checkout submission state instead of checkout validation.
| Code | Meaning | Recommended action |
|---|---|---|
invalid_input | A supplied value is malformed, empty, or uses the wrong resource type. | Correct the request before retrying. |
invalid_checkout_id | The value isn't a valid Shopify Checkout GID. | Correct the checkout ID before retrying. |
checkout_not_found | The checkout ID is validly formatted, but the checkout doesn't exist or is no longer available. | Start a new checkout. |
checkout_completion_throttled | Checkout submission is throttled. | Retry after the returned poll_after timestamp. |
checkout_completion_timeout | Shopify timed out while waiting for checkout completion. | Retry with the same idempotency key. |
checkout_completion_ineligible | The checkout can't be completed through the API. | Hand off through continue_url. |
Anchor to WarningsWarnings
Warnings are non-fatal messages. A warning can be returned by itself, or with errors in the same messages array. For example, Shopify can return a discount warning while still returning a checkout resource and continue_url.
Warning codes can vary by checkout configuration, discounts, inventory, and merchant capabilities. Don't rely on isError alone. Inspect the full messages array, message severities, continue_url, and the checkout status when a Checkout response is returned before deciding whether to call update_checkout, hand off to the buyer, or continue without the warning condition.