feat!: align embedded protocol errors with UCP error conventions

[westeezy]

Aligns ECP error and success responses with UCP's transport-agnostic conventions. What started as moving delegation errors from JSON-RPC error to result expanded into broader envelope, error model, and schema alignment.

UCP envelope on all ECP results

Every ECP request result now uses oneOf [success, error_response] with result.ucp.status as the discriminator — same pattern as REST and MCP. Applies to all checkout delegation methods (ec.ready, ec.auth, ec.payment.*, ec.fulfillment.*, ec.window.*) and cart methods (ep.cart.ready, ep.cart.auth). The JSON-RPC error field is reserved for transport-level failures only.

Decouple ucp.status from severity

Previously the spec coupled ucp.status: "error" to severity: "unrecoverable". This was accurate for REST/MCP (error_response replaces a missing resource) but breaks for ECP where delegation errors occur within a live session. ucp.status is now a pure shape discriminator; severity independently prescribes the action.

Schema refactoring

• ucp.json: Added $defs/success and $defs/error — shared building blocks replacing inline allOf + status const patterns
• embedded.openrpc.json: Extracted components/schemas for ucp_success, payment_instruments, payment_instrument_selection
• Removed embedded_error_code.json, embedded_message_error.json, embedded_error_response.json — three files duplicating the error chain for different examples on a freeform string. ECP error codes are documented in spec prose.

Other fixes

• ec.ready checkout: Replaced $ref to full checkout.json with inline partial type matching what ec.ready actually promises (display-only host hints)
• ec.ready failure lifecycle: Host MUST tear down on handshake error
• Notification cleanup: Reverted oneOf [resource, error_response] on messages.change notifications back to plain $ref — session errors go through ec.error / ep.cart.error

---

Type of change

Please delete options that are not relevant.

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing
  functionality to not work as expected, including removal of schema files
  or fields)
• Documentation update

---

Is this a Breaking Change or Removal?

If you checked "Breaking change" above, or if you are removing any schema
files or fields:

• I have added ! to my PR title (e.g., feat!: remove field).
• I have added justification below.

## Breaking Changes / Removal Justification

JSON-RPC 2.0 reserves the top-level error field for transport-level failures (parse errors, method not found, invalid params). Delegation outcomes like "user cancelled" or "payment method not supported" are application-level results — the RPC call succeeded, but the outcome was negative.

The previous design conflated these two failure planes, causing two problems:

  1. Middleware can't distinguish transport failures from domain outcomes.
  2. Inconsistency with other UCP transports — REST and MCP return domain errors inside the response body, not via transport error mechanisms.

Moving delegation errors to result.error restores correct JSON-RPC layering: error means the message itself failed; result.error means the delegation produced a negative outcome.

---

Checklist

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published in downstream modules

[westeezy]

Alternative worth exploring

This PR uses the standard error_response shape, but ECP's success responses nest under checkout while error_response does not — making type-safe discrimination less clean than in REST/MCP. It also puts ucp.version on host responses where the version semantics are ambiguous as what would happen if it differed from the initially negotiated version in the url ec_version.

A lighter shape that reuses Message but drops the ucp wrapper could sidestep both issues at the cost of symmetry could be:

{ "status": "error", "messages": [{ "type": "error", "code": "abort_error", "content": "...", "severity": "recoverable" }]

In this case result.status === "error" becomes a clean discriminator, and we remove the ambiguous version metadata from host-originated errors. However then ECP will differ from the transport error shape.

[igrigorik]

Thinking & writing out loud...

UCP's promise is to be transport-agnostic. REST and MCP deliver on this and ECP (unfortunately) is the outlier where this promise is broken. As a north star, we should work towards fixing this; we should prefer steps that get us closer to transport-agnostic promise instead of away or preserving status quo.

This PR is a step in the right direction. Moving delegation errors into result using error_response is correct, but it only fixes the error side, which creates the highlighted asymmetric discriminator: ucp.status exists on errors but not on success. And so, why not take the next logical step and complete it: adducp to the success side too.

// success
{ "result": {
    "ucp": { "version": "2026-01-15", "status": "success" },
    "checkout": { ... } }
}}

// error
{ "result": {
    "ucp": { "version": "2026-01-15", "status": "error" },
    "messages": [{ ... }]
}}

With that, ucp.status is a consistent discriminator on both branches, matching the same shape we have with REST and MCP. This applies to all delegation results:

• ec.ready: { ucp, upgrade?, checkout? } — the handshake ack now explicitly confirms the negotiated version
• ec.payment.*: { ucp, checkout } — partial update with envelope
• ec.fulfillment.*: same
• ec.window.open_request: { ucp } — the empty ack becomes a protocol-level confirmation instead of a structureless {}

I see all of the above as strict improvements. The version echo is the host explicitly confirming the negotiated ec_version -- similarly, explicit confirmation is a feature.

[westeezy]

@igrigorik I am aligned on that. We should be consistent across the transports. I think we should add language around when a version change is acceptable such as only during handshake, but none the less the UCP envelope being consistent feels correct and it feels like we should make the change all at once rather than piecemeal.

[mmohades]

Thanks so much Westin for putting this together to finally fix errors in EP! :)

I suggest a structural tweak to our error handling to match the other transports: let's treat transport-level failures as JSON-RPC protocol errors instead of wrapping them as UCP application outcomes.

Why this is better:

• Matches MCP & REST exactly: checkout-mcp.md already explicitly separates Protocol Errors (JSON-RPC error) from Business Outcomes (JSON-RPC result). Doing the same here means developers only need to learn one mental model for all of UCP.
• Reuses the MCP error schema: Following the established data.code and data.content pattern for errors ensures our API surface remains 100% consistent (as shown for MCP here).
• Keeps capability specs clean: A blocked popup or a cancelled sheet is failure by the Host to fulfill the requested interaction, not a commerce business logic failure.

So for example, instead of this:

{
  "jsonrpc": "2.0",
  "id": "auth_1",
  "result": {
    "ucp": { "status": "error" },
    "messages": [{ "type": "error", "code": "abort_error" }]
  }
}

We'd do

{
  "jsonrpc": "2.0",
  "id": "auth_1",
  "error": {
    "code": -32000,
    "message": "User aborted",
    "data": {
      "code": "aborted",
      "content": "The user closed the payment selection interface."
    }
  }
}

Then update error codes in overview.md with:

Embedded Protocol Errors:

These errors are returned as JSON-RPC error objects by the Host when it fails to fulfill a request (such as a delegation or auth request) initiated by the Business.

Code	Message	data.code	Meaning
-32000	"Unauthorized"	"unauthorized"	The request lacks valid authentication credentials or authorization to perform the operation (e.g., host origin validation failed).
-32000	"Request timed out"	"timeout"	The server or host did not fulfill the request within the allowed time period (e.g., network timeout during handshake).
-32000	"User aborted"	"aborted"	The client or user intentionally terminated the operation before it could be completed (e.g., closed the interface).
-32000	"Window open rejected"	"rejected"	The host understood the request but refused to fulfill or authorize the action due to local policy (e.g., blocked window navigation).
-32000	"Not allowed"	"not_allowed"	The requested operation cannot be performed in the current execution context (e.g., sending start before completing handshake).
-32601	"Method not found"	N/A	The method specified is not recognized or supported by the host.
-32603	"Internal error"	"internal"	An unexpected condition was encountered that prevented the request from being fulfilled.

---

@igrigorik @westeezy, and others please share your thoughts!

[igrigorik]

@mmohades I think this takes us in the wrong direction.

The separation we enforce is transport errors signal that the message itself couldn't be processed (malformed JSON, unknown method, invalid params); application errors capture results of executed business logic. A delegation with an aborted outcome is not a protocol error, it's a valid outcome: "I presented the payment sheet, the buyer declined." The host successfully processed the request and reported the result. That's what JSON-RPC result is for.

For auth, ec.auth is UCP application-level protocol for credential exchange. It's business logic that happens to use JSON-RPC as transport, not a JSON-RPC authentication mechanism. Auth outcomes (timeout, unsupported type, success) are results of that business logic executing, so they belong in result with severity guiding the next step.

Examples of transport errors would be calling missing / unsupported methods, malformed JSONRPC payload, etc. I pushed f1d2798 to address this in the stacked PR, because it allows us to avoid duplicating this across cart+checkout.

[mmohades]

Thanks Ilya! I see that we have different mental models here :D

My initial thinking was rooted in how the rest of UCP works. In all other transports like REST and MCP, "Application Errors" strictly map to commerce domain errors (like invalid_address or insufficient_inventory) which are computed and returned by the Business.

However, in the Embedded Protocol, the direction is inverted: the Host is responding with the result of an environment/UI interaction. From that perspective, viewing an aborted sheet as "I successfully presented the UI, and the valid outcome was the buyer declining" makes sense. It’s very much a GraphQL-style mental model where JSON-RPC acts purely as the delivery envelope, and I'm happy to align with that for interactive outcomes!

That said, to avoid any confusion for developers crossing between these transports, I think we should call out:

1. Explicitly document this mental model: Let's add a short paragraph to the Error Handling section explaining this boundary. Without clarifying that we treat interactive/auth outcomes as application results, developers coming from traditional REST/RPC backgrounds might be confused as to why a failure returns a successful JSON RPC result envelope.
2. Be explicit with protocol-level boundaries: When a request can't be safely ingested or authorized (e.g., malformed JSON, unknown methods, or failed origin validation), let's explicitly return a top-level JSON-RPC error. This creates a clear signal for developers that the execution failed at the protocol boundary and never reached the business logic layer.
3. Highlight the unique direction of Embedded errors: Adding a quick note that outcome errors in ECP/ECaP are returned by the Host (versus the Business in REST/MCP) will make the spec much easier to digest contextually.

Protocol Errors

{
  "jsonrpc": "2.0",
  "id": "req_1",
  "error": {
    "code": -32600,
    "message": "Invalid Request",
    "data": {
      "code": "invalid_request",
      "content": "Host origin validation failed during handshake."
    }
  }
}

Code	Message	data.code	Meaning
-32700	"Parse error"	N/A	Invalid JSON was received by the host.
-32600	"Invalid Request"	"invalid_request"	The JSON sent is not a valid Request object or lacks valid origin (e.g., host origin validation failed).
-32601	"Method not found"	N/A	The method specified is not recognized or supported by the host.
-32602	"Invalid params"	"invalid_params"	Invalid method parameter(s) were provided.
-32603	"Internal error"	"internal"	An unexpected condition was encountered that prevented the request from being fulfilled.

Application Errors

{
  "jsonrpc": "2.0",
  "id": "req_2",
  "result": {
    "status": "error",
    "messages": [
      {
        "type": "error",
        "code": "abort",
        "content": "The buyer closed the payment selection sheet.",
        "severity": "recoverable"
      }
    ]
  }
}

Code	Severity	Trigger / Scenario
abort	recoverable	The buyer closed the sheet, declined the prompt, or cancelled the flow.
not_supported	unrecoverable	The requested auth, payment method change, credential, etc is not supported.
timeout	recoverable	The request processing didn't finish in the expected time.
not_allowed	recoverable	The request is not allowed in the current context (e.g. ec.start sent before handshake completed.)
window_open_rejected	unrecoverable	Host policy or environment restrictions blocked the requested navigation/window.

[jingyli]

Thanks @westeezy @igrigorik, the main constructs LGTM! Left some style-related comments + 2 structural ones related to:

1. Should delegation response echo back the entire checkout object? If not, should we clarify why (is it because host wouldn't hold/be responsible for the other business-only fields) and clean up the comment in the examples?
2. By removing error_response from xx.messages.change, how will business notify host on actually unrecoverable errors where the resource is no longer being maintained on their end..? Are we expecting them to send that via xx.error as well?

Can approve from my end once the 2 points above are resolved!

Also a fly-by comment to @mmohades's note above, specifically on this:

Highlight the unique direction of Embedded errors: Adding a quick note that outcome errors in ECP/ECaP are returned by the Host (versus the Business in REST/MCP) will make the spec much easier to digest contextually.

I think there is actually an exception to this point, namely xx.error messages like https://ucp.dev/draft/specification/embedded-cart/#epcarterror where outcome errors are also being sent in the direction of Embedded Cart/Checkout -> host.

[jingyli]

Naive QQ: Should this be **MUST** instead? Is it **SHOULD** only because we anticipate severity: "requires_escalation" to be a legitimate alternative..?

[igrigorik]

requires_escalation is a checkout status, not a severity — the severity values are recoverable, requires_buyer_input, requires_buyer_review, unrecoverable. When no resource exists, unrecoverable is correct, because there's nothing to recover against.

We're using SHOULD instead of MUST because error_response is also used in ECP delegation results where the session is still alive and recoverable is valid (e.g., user cancelled a payment sheet). The constraint is accurate for REST/MCP but too strict as a universal rule. The error processing algorithm is now updated to route on severity instead of short-circuiting on ucp.status — so the behavior is the same for REST/MCP (unrecoverable -> retry with new resource), but ECP delegation errors can flow through severity-based routing correctly.

[jingyli]

The host MUST tear down the embedded context and MAY redirect the buyer to
continue_url if present. The Embedded Cart MUST NOT send further
messages after receiving a handshake error.

I wonder if this is missing a step in-between? In my mind, the following makes slightly more sense:

1. Host responds with error_response
2. Embedded Cart echoes with ep.cart.error containing a possible continue_url
3. Upon receiving 2), host proceed with tear down & redirect
4. Embedded Cart MUST NOT send further messages

Without step 2), I don't think there is any opportunity for host to ever receive the continue_url from business for handoff.

[igrigorik]

The host initiated the embedded flow, it already has the cart/checkout response from the previous step, including continue_url. A handshake failure should be terminal: host sends error response, tears down. To recover, the host can retry the embedded session or fall back to continue_url from the original cart/checkout response. No echo needed — the host has full context from before it loaded the iframe

[westeezy]

I agree with @igrigorik in this regards. The continue_url should already be available and in terminal errors I wouldn't expect step 2.

[jingyli]

To confirm on the expectation here: Does this mean in these delegation responses, we would only get back the delta data (i.e. updated fulfillment) and won't actually get the entire checkout object back again?

This feels like it differs from other transport and also differs from what the example in https://ucp.dev/draft/specification/embedded-checkout/#ecfulfillmentchange mentions..?

[igrigorik]

This is consistent with other delegation responses in embedded, wihch return only the delta.

The spec prose already describes this: "The Embedded Checkout MUST treat this update as a PUT-style change by entirely replacing the existing state for the provided fields." The example in the spec matches; it shows only checkout.fulfillment, not the full checkout object.

[westeezy]

@jingyli I think this also may answer your question in another comment of should the delegations echo back the entire checkout object and my response would be no as this precedent exists.

[igrigorik]

@jingyli responded to your questions, ptal.

@mmohades:

1. Document the mental model: The two-layer model (transport errors vs business outcomes) is defined in overview.md and referenced by each transport spec. For embedded, docs: extract shared EP core, group transports in nav #339 adds this to the shared embedded-protocol.md Response Handling section — same pattern checkout-mcp and catalog-mcp already use.
2. Protocol error boundaries: Also in docs: extract shared EP core, group transports in nav #339 — embedded-protocol.md now has a Transport Errors section with a concrete -32601 example and pointer to the error code registry in overview.md.
3. Direction: as @jingyli noted above, the direction isn't uniformly inverted — ec.error / ep.cart.error flow business->host. The error model is direction-agnostic; what matters is transport vs application, not who sends it. The error code tables in docs: extract shared EP core, group transports in nav #339 cover both shared codes (abort_error, security_error, etc.) and capability-specific codes (not_allowed_error, window_open_rejected_error in checkout).

In short, I believe we have right end-state once we land this and 339. I'm sure further improvements can be made, but I don't think we should block our version cut and release; I think we're in good state to land and iterate in followup PRs.

[jingyli]

Thanks @igrigorik! My outstanding questions are resolved between #339 and inline responses here.

[westeezy]

Appreciate the callout to better docs. I gave #339 a read and an approval as I felt it did address the potential for confusion. If we view these two PRs both landing I am hopeful the documentation comments are addressed. I don't see anything that I feel would remain open or unaccounted for based on the comments thus far but please correct me if I am wrong.

My stance at the moment is this feels like between the two PRs are are in a good spot to merge.

[igrigorik]

Thanks all! Landing this so we can unblock and merge 339.

@mmohades if you feel there are still gaps to improve, let's spin up a new issue/PR and iterate.