Errors & status

Layout never claims an order is placed without evidence, and a confident false failure is just as dangerous. Handle the uncertain state deliberately.

placed vs failed vs unconfirmed

Three terminal states, and they are not interchangeable:

placed — the order reached the merchant, backed by a confirmation screen and upgraded by the receipt email. Safe to tell the person it's ordered.
failed — it did not go through, with a reason code. Nothing was charged; it is safe to try again.
unconfirmed — Layout could not verify either way. Do not retry automatically and do not show “failed.” Surface it as pending and let the person or your support flow resolve it. Collapsing this into failed is what causes duplicate orders and double charges.

{
  "error": {
    "code": "price_changed",
    "message": "The total moved since the cart was shown.",
    "orderId": "ord_7c21"
  }
}

Code	Meaning
`unauthorized`	Bad or missing client secret.
`build_only`	The session tried to confirm or spend. That only happens on the hosted link.
`not_orderable`	The store can't be ordered from right now (closed, removed, or unsupported).
`price_changed`	The total moved since the cart was shown. Re-show it and confirm again.
`needs_approval`	A money ceremony is required; the person completes it on a hosted link.
`rate_limited`	Too many requests. Back off and retry.

When genuinely uncertain, say so. A check that cannot run has no opinion — it does not veto, and it does not invent a failure.