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 restaurant, with evidence. Safe to tell the person it's ordered.
• failed: it did not go through, with a reason code. Whether trying again can work depends on the code: see Failure codes. Do not tell the person “nothing was charged” on every failure: see Holds on a failed order.
• unconfirmed: Layout could not verify either way. Do not retry it, automatically or by hand, and do not treat it as failed. Wait for order.placed or read GET /v1/orders/:id, and show it as pending meanwhile. Collapsing this into failed is what causes duplicate orders and double charges.

An unconfirmed order is not abandoned. Layout keeps working it: when the store's own confirmation email arrives, the order moves to placed and you receive order.placed, and a person at Layout is alerted to settle the rest with the store. There is no fixed deadline, so keep the order open and let the next webhook or GET /v1/orders/:id decide it. Tell the person something like: “We're confirming your order with the store. Don't order again yet; we'll let you know.”

A refund is settled between the person and Layout support. No event is sent for it, and you do not need to act on one.

Error shape

Every error the /v1 endpoints send has the same shape.

{
  "error": {
    "code": "price_changed",
    "message": "This cart's price no longer matches the total you sent.",
    "orderId": "ord_7c21e4b9a0d3"
  }
}

code is always one of the list below, the Error schema in openapi.json. Switch on code, never on message. The other fields appear only where they apply:

Two different fields carry codes, and they never mix. error.code, lowercase (card_declined), answers a request Layout refused. failure_code, uppercase (CARD_DECLINED), is how an order ended, on the order and its order.failed webhook (see Failure codes). A card refused at confirm is the first; a card refused later, during placement, is the second.

A request no endpoint handles is 404 in the standard shape, { "error": { "code": "not_found", "message": "No route answers GET /v1/…" } }, with X-Request-Id and Layout-Version. Two answers come from in front of the endpoints, and they are flat, with error a string: a write that carries a browser Origin Layout does not allow is 403 { "error": "bad_origin" }, and an outage at Layout's edge can be 503 { "error": "unavailable" }. Read error as a string when it is not an object, and treat the status as you would the matching code below.

Every error code

insufficient_scope, confirm_required and moved_to_mcp are reserved and not sent.

Paths starting /confirm, /answer or /cancel are on a cart, POST /v1/carts/:id/…. See Confirm for how a confirm walks through them. Every answer from an endpoint, errors included, carries X-Request-Id: quote it when you write to support.

Failure codes

A failed order carries its reason as failure_code on GET /v1/orders/:id, and an unconfirmed one carries UNCONFIRMED. It is a stable machine code, never prose, and it is the only failure field the API exposes. Switch on state first: an order still placing can carry a code before it settles. An order.failed webhook carries the same code as order.failure_code; no other event carries it. These are the values Layout sends, and Layout maps an older stored value to one of them. Treat any value you do not know as UNKNOWN. Each row says whether a new cart can work; none of them is a reason to retry an unconfirmed order.

A cart that could not be built says why in failure.code on GET /v1/carts/:id, with failure.message written for the person. It is one of the codes above when Layout classified the failure, and otherwise a lowercase word for how the build ended, such as build_stopped. Show failure.message, and treat a code you do not know as UNKNOWN.

Holds on a failed order

A failed order was not placed, but the person's card may have carried a hold for it. When an order fails, Layout voids any hold it placed. If the void cannot be confirmed, a pending hold can still show on the card. It is not a charge, and it drops off on its own if the order did not go through. In the rare case money did move, Layout support makes it right with the person. The order and its webhook do not say which of these happened, so do not tell the person “nothing was charged” on every failure. Say the order was not placed, and that any pending hold drops off on its own.

Why refusals never say why

A 401 other than grant_expired carries the same body whatever the underlying reason, and so does a 403 other than wrong_credential from anything but your own secret:

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API credentials."
  }
}

Separating “no such key” from “right key, wrong permission” would let someone measure how close a guess landed. So a 401 never varies. A 403 means the secret itself matched, so its holder is told why with error.reason, beside the same code and message:

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API credentials.",
    "reason": "live_not_approved"
  }
}

You also get every refusal under Refused requests on your application's Credentials page in the console, with a count and a last-seen time, and from layout refusals in the CLI. A refused person token or build grant is not recorded there.

A secret that matches no application at all gets refused and logged nowhere. Otherwise anyone could fill that list with noise.

409 already_claimed

If someone you provisioned but never verified signs up to Layout on their own, the account is theirs. verify/start and POST /v1/users/:id/grant then answer 409 already_claimed.

Do not retry past it. Ordering for them is now theirs to agree to: ask them to connect your application with POST /v1/users/:id/connect. Once they approve, grants work again.