Errors and messages

A UCP call to a Monokaido shop can go wrong in two very different ways. Either the request could not be processed at all — a protocol error, with an HTTP error status — or it was processed and the shop has something to say about the outcome — a message, inside an ordinary 200 answer. This chapter shows how to tell the answers apart and lists every code the API returns, with what your client should do about each.

The examples use the shop https://shop.example.com and a platform whose profile is https://platform.example.com/.well-known/ucp. When to retry, and how, is covered in detail in Idempotency, concurrency and limits.

Three kinds of answer

Two more kinds of answer are not UCP JSON at all:

• The web server's own pages. The web server in front of the shop answers a few situations itself, before the API sees the request, with an HTML page: plain http://, a body over 1 MiB, too many requests per second, the API unreachable or too slow. See Answers that are not JSON.
• The handoff page. continue_url is a page for the buyer's browser. The API serves it on the shop's domain, as HTML. Your client never needs to call it.

Telling them apart

Check an answer in this order:

A successful answer never carries ucp.status: read its absence as success. No 2xx answer of the API other than 200 and 201 exists, and the API never redirects (the web server redirects plain http:// to https:// with a 301; call https:// directly).

// Sort one UCP answer into the kinds above (Node 20+ fetch Response).
async function readUcp(res) {
  const retryAfter = Number(res.headers.get('retry-after')) || undefined;
  if (res.status === 304) return { kind: 'not_modified' };
  if (!(res.headers.get('content-type') ?? '').startsWith('application/json')) {
    // nginx's own HTML page: 413, 429, 502 or 504. Decide by the status alone.
    return { kind: 'web_server', status: res.status };
  }
  const body = await res.json();
  if (res.status >= 400) {
    return { kind: 'protocol_error', status: res.status, code: body.code,
             content: body.content, continueUrl: body.continue_url, retryAfter };
  }
  if (body.ucp?.status === 'error') {
    return { kind: 'business_error', code: body.messages[0].code,
             messages: body.messages, continueUrl: body.continue_url };
  }
  return { kind: 'resource', status: res.status, body, messages: body.messages ?? [] };
}

# Sort one UCP answer into the kinds above (a requests.Response).
def read_ucp(r):
    retry_after = r.headers.get("Retry-After")
    if r.status_code == 304:
        return {"kind": "not_modified"}
    if not r.headers.get("Content-Type", "").startswith("application/json"):
        # nginx's own HTML page: 413, 429, 502 or 504. Decide by the status alone.
        return {"kind": "web_server", "status": r.status_code}
    body = r.json()
    if r.status_code >= 400:
        return {"kind": "protocol_error", "status": r.status_code, "code": body["code"],
                "content": body["content"], "continue_url": body.get("continue_url"),
                "retry_after": int(retry_after) if retry_after else None}
    if body.get("ucp", {}).get("status") == "error":
        return {"kind": "business_error", "code": body["messages"][0]["code"],
                "messages": body["messages"], "continue_url": body.get("continue_url")}
    return {"kind": "resource", "status": r.status_code, "body": body,
            "messages": body.get("messages", [])}

Protocol errors

The body and headers

A protocol error has exactly two or three keys:

Every protocol error is sent with Cache-Control: no-store. Retry-After, in whole seconds, is sent with these and no others:

{
  "code": "service_unavailable",
  "content": "Another request on this session is being processed — retry shortly"
}

The protocol error codes are invalid_profile_url, profile_unreachable, profile_malformed, version_unsupported, invalid_request, request_too_large, not_found, idempotency_conflict, rate_limited, service_unavailable and internal_error. The negotiation code capabilities_incompatible is not among them: it arrives as a business error with HTTP 200.

The shop, the host and the route

A missing cart, checkout or product is never a 404: it is a business error with HTTP 200.

Your platform profile

These come from the UCP-Agent header and the platform profile it names. All of them carry continue_url, the shop's home page. Each request runs the checks in this order: the header, the fetch, the version, then the capability negotiation.

{
  "code": "profile_unreachable",
  "content": "Unable to fetch the platform profile",
  "continue_url": "https://shop.example.com/"
}

The request

The fields are checked only once the session is found and open. A PUT to an unknown, completed, canceled or handed-over session gets that session's answer — not_found, checkout_completed, checkout_canceled or handed_off — with HTTP 200, without its fields being read (only a body that is not a JSON object is refused first). Such an answer says nothing about whether your body was valid.

Send every body with Content-Type: application/json. A body sent as text/plain, as another +json type, or without a Content-Type, is not read: the catalog search then runs as an empty search, and lookup, product and every cart and checkout create or PUT answer 400 request must be an object. A form-encoded body (application/x-www-form-urlencoded) is parsed, but every value in it arrives as a string, so a numeric field such as quantity or pagination.limit is refused with 400 invalid_request. Do not use it.

Idempotency and concurrency

The first 409 has one rare second cause: two copies of the same request raced, and the first one failed and released the key while the second looked it up. If you are certain both copies were identical, one more retry with the same key runs the request.

Limits and failures

{
  "code": "rate_limited",
  "content": "Too many requests"
}

Every field error

The content of a 400 invalid_request is one of these sentences. <i> is the index in the array you sent; <field> is the name of a text field.

What is adjusted instead of refused

Some values are corrected without an error. Compare what you sent with the answer:

Business errors

A business error is an HTTP 200 whose ucp.status is "error". It returns no resource — no id, no lines — only messages with one entry and a continue_url:

{
  "ucp": {
    "version": "2026-04-08",
    "status": "error",
    "capabilities": {
      "dev.ucp.shopping.cart": [
        {
          "version": "2026-04-08"
        }
      ],
      "dev.ucp.shopping.discount": [
        {
          "version": "2026-04-08"
        }
      ]
    }
  },
  "messages": [
    {
      "type": "error",
      "code": "not_found",
      "content": "Cart not found or has expired",
      "severity": "unrecoverable"
    }
  ],
  "continue_url": "https://shop.example.com/"
}

Every business error severity is unrecoverable: the same request will get the same answer. A business error on a write is a result like any other, so it is stored with the Idempotency-Key and a retry with that key gets it again — use a new key when you try again with a changed request.

Messages

The message object

Where messages appears:

Severity and what it asks of you

A checkout's status follows from its messages: any error with severity recoverable makes it incomplete; otherwise it is requires_escalation and carries payment_required. The messages of a checkout come in this order: line messages, discount messages, then what the checkout lacks, and payment_required last.

Line messages

Carts and checkouts, on create and on every write that sends line_items (also when a language change re-prices the lines). They appear only in the answer to the write that caused them: the line is already removed or lowered in that answer, so the next read of a checkout can return requires_escalation without them.

<id> is the item.id as you sent it (trimmed). The messages about one variant — cannot be bought right now, vat_mix_not_allowed and out_of_stock — name the first id you sent for that variant.

Discount messages

With the discount extension negotiated, on every create and PUT of a cart or checkout, a cart's conversion included. Codes are tried in the order you sent them, and the first one the shop accepts is applied.

On a session whose lines were all removed, codes are judged against a total of 0: a code with a minimum order total gets discount_code_user_ineligible, and any other code the shop accepts is applied without a message but takes nothing off, so discounts.applied stays empty.

<i> counts in the list as the API keeps it: duplicates (compared without regard to case) and blank codes removed. A refused code stays stored and is tried again on the next write; send discounts.codes without it to drop it.

Checkout readiness

Derived anew on every create, PUT, GET and POST …/complete of an open checkout — once the buyer has taken it to the shop, the last answer before the handoff is repeated instead. The fulfillment messages appear only when the fulfillment extension is negotiated.

Closed and handed-over sessions

These messages can also arrive on a write that raced with the order or with the deadline: the answer is then the session as it is now, closed.

{
  "ucp": {
    "version": "2026-04-08",
    "capabilities": {
      "dev.ucp.shopping.checkout": [
        {
          "version": "2026-04-08"
        }
      ],
      "dev.ucp.shopping.fulfillment": [
        {
          "version": "2026-04-08"
        }
      ],
      "dev.ucp.shopping.discount": [
        {
          "version": "2026-04-08"
        }
      ]
    },
    "payment_handlers": {}
  },
  "id": "3d7b9e2a-6f14-4c58-9b3e-8a2f1c6d4e97",
  "buyer": {
    "email": "jana.novakova@example.com",
    "last_name": "Nováková",
    "first_name": "Jana",
    "phone_number": "+421 905 123 456"
  },
  "links": [
    {
      "url": "https://shop.example.com/obchodne-podmienky",
      "type": "terms_of_service",
      "title": "Obchodné podmienky"
    },
    {
      "url": "https://shop.example.com/ochrana-osobnych-udajov",
      "type": "privacy_policy",
      "title": "Ochrana osobných údajov"
    }
  ],
  "status": "requires_escalation",
  "totals": [
    {
      "type": "subtotal",
      "amount": 71880
    },
    {
      "type": "discount",
      "amount": -5844,
      "display_text": "JESEN10"
    },
    {
      "type": "fulfillment",
      "amount": 490
    },
    {
      "type": "total",
      "amount": 66526
    }
  ],
  "context": {
    "language": "sk",
    "address_country": "SK"
  },
  "currency": "EUR",
  "messages": [
    {
      "code": "payment_required",
      "type": "error",
      "content": "Payment is completed on the shop website — continue there to place the order",
      "severity": "requires_buyer_input"
    },
    {
      "type": "warning",
      "code": "handed_off",
      "content": "The buyer continued on the shop: the items are in the shop’s cart now and this session is no longer changed"
    }
  ],
  "discounts": {
    "codes": [
      "JESEN10"
    ],
    "applied": [
      {
        "code": "JESEN10",
        "title": "JESEN10",
        "amount": 5844,
        "method": "across"
      }
    ]
  },
  "expires_at": "2026-10-27T09:21:30.551Z",
  "line_items": [
    {
      "id": "f6a3c8e1-9d27-4b54-8e6a-2c1f7b9d3a58",
      "item": {
        "id": "1e8a6c4f-2b93-4d71-9f05-6a3c8e2b1d47",
        "price": 69900,
        "title": "Trek Marlin 5",
        "image_url": "https://shop.example.com/api/public/uploads/c4d1e5a2-8b3f-4a6c-9e07-5f2d8a1b3c40/products/trek-marlin-5-modra.webp"
      },
      "totals": [
        {
          "type": "subtotal",
          "amount": 69900
        },
        {
          "type": "total",
          "amount": 69900
        }
      ],
      "quantity": 1
    },
    {
      "id": "2e9d5b7a-4c83-4f16-a9b2-6d8e1c3f7a49",
      "item": {
        "id": "b5f81c3d-6e49-4a2b-8d73-9c0e4f1a6b25",
        "price": 990,
        "title": "Fľaša na vodu 750 ml"
      },
      "totals": [
        {
          "type": "subtotal",
          "amount": 1980
        },
        {
          "type": "total",
          "amount": 1980
        }
      ],
      "quantity": 2
    }
  ],
  "fulfillment": {
    "methods": [
      {
        "id": "shipping",
        "type": "shipping",
        "groups": [
          {
            "id": "default",
            "options": [
              {
                "id": "0c5e8a3f-7b21-4d96-8f4c-9e2a6d1b3c75",
                "title": "GLS kuriér",
                "totals": [
                  {
                    "type": "total",
                    "amount": 490
                  }
                ],
                "description": "Doručenie na adresu do 1–2 pracovných dní"
              },
              {
                "id": "6b2d9f4e-3a17-4c68-9d5b-1f8e3a7c2b40",
                "title": "Packeta – výdajné miesto",
                "totals": [
                  {
                    "type": "total",
                    "amount": 290
                  }
                ],
                "description": "Delivery in 2–3 business days"
              }
            ],
            "line_item_ids": [
              "f6a3c8e1-9d27-4b54-8e6a-2c1f7b9d3a58",
              "2e9d5b7a-4c83-4f16-a9b2-6d8e1c3f7a49"
            ],
            "selected_option_id": "0c5e8a3f-7b21-4d96-8f4c-9e2a6d1b3c75"
          }
        ],
        "destinations": [
          {
            "id": "destination",
            "last_name": "Nováková",
            "first_name": "Jana",
            "postal_code": "811 01",
            "street_address": "Hlavná 12",
            "address_country": "SK",
            "address_locality": "Bratislava"
          }
        ],
        "line_item_ids": [
          "f6a3c8e1-9d27-4b54-8e6a-2c1f7b9d3a58",
          "2e9d5b7a-4c83-4f16-a9b2-6d8e1c3f7a49"
        ],
        "selected_destination_id": "destination"
      }
    ]
  },
  "continue_url": "https://shop.example.com/ucp/continue/9bbd3dedf887f93c6287fa7f4b8de141501155714c3b2050bb83551e36ec780b"
}

Catalog messages

Showing messages to the buyer

content is English and written for developers. Build the text you show the buyer from code and path, in the buyer's language, and keep content for your logs. Three rules cover every message:

1. Act on recoverable errors yourself, by sending what path names.
2. Show warnings as the change they describe — "only 2 in stock, quantity lowered" — because the answer already contains the changed state.
3. Pass requires_buyer_input to the buyer together with continue_url.

Codes may be added in the future. Handle an unknown code by its type and severity, never by failing.

Answers that are not JSON

The web server

The web server in front of every shop answers these itself, before the API sees the request. The body is a short HTML page, not JSON.

<html>
<head><title>429 Too Many Requests</title></head>
<body>
<center><h1>429 Too Many Requests</h1></center>
<hr><center>nginx</center>
</body>
</html>

Paths the web server does not send to the API — upper-case /UCP/…, /.well-known/ucp/ with a trailing slash, /ucp without the rest — reach the shop's web pages and answer with HTML as well. Use the paths exactly as published.

The handoff routes

continue_url (GET /ucp/continue/<token>) is opened by the buyer's browser, and its page sends POST /ucp/continue/<token> itself. Your client calls neither, but you may see these answers reported by buyers:

The page retries a 5xx, a 429 or a lost connection twice, after 1 and 2 seconds, then sends the browser to the shop's checkout, cart or home page without the lines. If your platform keeps polling a session the buyer is opening, keep at most one request in flight, so the buyer's claim gets its turn.

What to log

The API returns no request id. For every call, log at least the time in UTC, the host, the method and path, the HTTP status, code (or the message codes) and your own correlation id. Send that id as X-Request-ID too: the shop's web server writes it into its access log (it is not returned), so a problem can be found on Monokaido's side. Put nothing secret in it. Cart and checkout ids are credentials: keep them out of logs that other parties can read — see Security and data protection.