Responses and errors

Every response from the API has the same outer shape, and every error has a stable code you can branch on. Branch on error.code, not on the HTTP status or the message: several codes share a status, and messages can be reworded.

SuccessCopy Anchor Link

A successful response wraps its result in data:

{ "data": { "id": 101, "name": "Oak desk lamp", "slug": "oak-desk-lamp" } }

Lists add links and meta for pagination. Some responses add a meta object with extra facts, such as meta.order_access_token after a guest checkout or meta.shipping_option_cleared after an address change.

• Times are ISO 8601, in UTC.
• Money is always a money object, never a bare number.
• New fields can appear at any time, so ignore fields you do not know. See versioning.

ErrorsCopy Anchor Link

Every error uses one envelope:

{
  "error": {
    "code": "COUPON_NOT_APPLICABLE",
    "message": "Spend £20.00 more to use this code.",
    "details": {
      "code": ["Spend £20.00 more to use this code."],
      "reason": "threshold",
      "remaining": { "amount": 2000, "currency": "GBP", "formatted": "£20.00" }
    }
  }
}

Every response also carries an X-Request-Id header. Log it, and quote it if you contact support about a request.

Validation errorsCopy Anchor Link

422 VALIDATION_FAILED means the request was understood but some input was refused. details maps each refused field to a list of messages. Nested fields use dots:

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "The billing.postcode field is required. (and 1 more error)",
    "details": {
      "billing.postcode": ["The billing.postcode field is required."],
      "billing.country_id": ["The billing.country_id field is required."]
    }
  }
}

Show each message next to its field. A few business checks use VALIDATION_FAILED too, under a key that is not a request field: for example, an item that has run out of stock at checkout is reported under cart.

Error codesCopy Anchor Link

Store and accessCopy Anchor Link

RequestsCopy Anchor Link

CartsCopy Anchor Link

Checkout and paymentsCopy Anchor Link

Accounts, content and CRMCopy Anchor Link

Which errors to retryCopy Anchor Link

Use exponential backoff with jitter for automatic retries, and stop after a few attempts.

const res = await fetch(url, init)

if (!res.ok) {
  const { error } = await res.json()
  switch (error.code) {
    case 'VALIDATION_FAILED':
      return showFieldErrors(error.details)
    case 'CART_NOT_FOUND':
      return startNewCart()
    case 'RATE_LIMITED':
      return retryAfter(Number(res.headers.get('Retry-After') ?? 1))
    default:
      console.error(error.code, error.message, res.headers.get('X-Request-Id'))
      return showGenericError()
  }
}