Errors

The error envelope

Errors do not reuse the success envelope. They carry an extra status field and nest the message one level deeper:

{ "statusCode": 200, "message": null, "data": { "...": "..." } }

{ "statusCode": 401, "status": "failed", "data": { "message": "Unauthorized" } }

Read the message from data.message. Read the status from the HTTP status line — the statusCode field mirrors it and is there for clients that lose the status line through a proxy.

One exception worth knowing before you write a parser: a request that never reaches a mounted route is answered by the framework’s not-found handler, which returns {"statusCode":404,"status":"failed","data":{"message":"Cannot GET /the/path"}}. If you see that Cannot <METHOD> <path> string, the route does not exist on that host — it is not an auth or permission failure. A route that exists but rejects you returns 401, not 404, except where noted below.

HTTP status usage

Status	Meaning
`200`	Success. Payload in `data`.
`400`	Request rejected — validation, or a state machine that will not accept the transition.
`401`	Missing or invalid credential.
`402`	Payment required — the x402 challenge. The body is the payment descriptor, not an error. See Agentic payments (x402).
`403`	Authenticated, but not permitted (for example a customer token attempting a merchant-only action).
`404`	Not found — also returned for a resource that exists but belongs to another tenant. Cross-tenant reads are deliberately indistinguishable from “does not exist”.
`429`	Throttled. See Rate limits.
`503`	A dependency is disabled or unreachable (feature flag off, facilitator down).

Codes you will hit

These are stable, machine-readable strings. Match on the code, never on the message text.

Checkout and PSP readiness

Returned by GET /checkout/:shopUrl/payment-intent-resolver, inside data.meta.breakerSkipped[], to explain why a payment method the shop nominally has is not being offered:

Code	`detail`	Meaning
`PSP_ACCOUNT_NOT_READY`	`STRIPE_CHARGES_DISABLED`	The merchant’s connected account exists but Stripe has not enabled charges on it. Do not render the card slot.

A live response for a shop in that state:

{
  "statusCode": 200,
  "message": null,
  "data": {
    "card": { "provider": null, "label": "", "accountId": null, "renderer": null, "publishableKey": null },
    "paypal": null,
    "crypto": null,
    "x402": null,
    "wallet": [],
    "currency": { "abbreviation": "USD", "symbol": "$", "conversionRateToUSD": 1 },
    "meta": {
      "resolvedAt": "2026-09-20T23:29:59.092Z",
      "source": "shopPaymentMethodsV2",
      "shopId": "<shop id>",
      "breakerSkipped": [
        { "provider": "STRIPE", "reason": "PSP_ACCOUNT_NOT_READY", "detail": "STRIPE_CHARGES_DISABLED" }
      ]
    }
  }
}

Resolve payment availability at request time from this endpoint. A shop’s configured method list is not the same thing as a method that can take money right now.

x402 settlement

Code	Status	Meaning
`X402_NOT_CONFIGURED`	`503`	x402 is enabled but no facilitator URL is configured on this environment.
`X402_FACILITATOR_UNAVAILABLE`	`503`	The facilitator is configured but unreachable, or its circuit breaker is open.
`X402_ORDER_NOT_CONFIRMABLE`	`400`	The order is not in a payable state.
`X402_SETTLE_FAILED`	`400`	The facilitator rejected the settlement; the reason is appended to the message.
`MERCHANT_PAYOUT_WALLET_UNSET`	—	Emitted when a settlement would have no merchant destination. Counted, not raised to the caller.

Agent surfaces

Code	Meaning
`AGENT_CHECKOUT_MANIFEST_DISABLED`	The agent checkout manifest is not enabled on this environment. The MCP tool returns this as an `isError` result, not an HTTP failure.

Throttling

{ "statusCode": 429, "status": "failed", "data": { "message": "ThrottlerException: Too Many Requests" } }

What to do with an unknown code

Codes are added as subsystems learn to explain themselves. Treat an unrecognised reason/code as a hard failure for that path — do not fall through to a different payment method on your side. If a code you are seeing is not listed here, tell us: an uncatalogued code is a documentation bug.

Overview

Admin API

Public API

Trust Fabric API

EAS Schemas (Trust Fabric)

Merchant API

AI Endpoints

Merchant

Customer

Shop

Product

Collection

SKU

Shipping

Gift Card

Blog

Cart

Order

Address Book

The error envelope

HTTP status usage

Codes you will hit

Checkout and PSP readiness

x402 settlement

Agent surfaces

Throttling

What to do with an unknown code

​The error envelope

​HTTP status usage

​Codes you will hit

​Checkout and PSP readiness

​x402 settlement

​Agent surfaces

​Throttling

​What to do with an unknown code

The error envelope

HTTP status usage

Codes you will hit

Checkout and PSP readiness

x402 settlement

Agent surfaces

Throttling

What to do with an unknown code