Transport Failures

Transport failures

A store's UCP profile can declare MCP, REST, A2A (the store agent) and Embedded (the store's own checkout page, Embedded Checkout Protocol). The Playground uses all four. Separately from UCP, a store page can offer its own WebMCP tools. Each has its own failure modes; knowing which layer failed is the first step.

MCP failures

MCP uses JSON-RPC over HTTP. Failures surface as either JSON-RPC error codes or HTTP-level errors from the endpoint.

-32601 · Method not found

The store's MCP server does not recognise the tool name. Either the store implements only some UCP tools, or the name is misspelled in the request.

FixList the store's tools in Inspect (the Tools view) and match names exactly. A missing tool may be served over REST instead.

-32000 · Authentication failed

The request lacked valid credentials.

FixSee Authorization Failures for the OAuth handshake and its failure modes.

-32603 · Internal error

The MCP server accepted the call but the tool itself failed while running, often because of an unhandled null or a database error in the store's implementation.

FixSend the same call in Inspect with the same arguments, and check the store's server logs for the failing tool.

HTTP 4xx / 5xx

The endpoint returned an HTTP error before JSON-RPC processing: expired SSL certificates (502), rate limiting (429), or the endpoint down (503).

FixConfirm with curl outside the harness. Transport-level HTTP errors are infrastructure, not protocol.

json
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32601,
    "message": "Method not found"
  }
}

REST failures

REST is used for REST-only stores, when you choose REST under Calls go over in Inspect, and as a fallback when MCP fails for specific tools.

404 Not Found

The REST endpoint path does not exist.

FixCheck that the store publishes REST endpoints at the paths the spec defines. See REST API fallback.

500 Internal Server Error

The server errored processing the request.

FixCheck the store's server logs. The run's Trace tab has the exact request body that triggered it.

CORS errors

Missing Access-Control-Allow-Origin headers prevent browser-based agents from reaching the endpoint. The Playground calls your endpoints from its own servers, so CORS doesn't affect its runs.

FixAdd CORS headers on the store's endpoint if browser-based agents need to call it.

A2A failures

Over A2A, the Playground reads the store agent's card first, then sends checkout actions as JSON-RPC messages. A card that can't be used stops a run before the first model call, and /runs says why before you send.

The profile declares no A2A service

The store's UCP profile has no dev.ucp.shopping entry with "transport": "a2a".

FixAdd one whose endpoint is the agent card's URL.

The agent card does not advertise the UCP extension

The card lists no extension URI https://ucp.dev/{version}/specification/reference, so UCP checkout can't be turned on over A2A.

FixList the extension in the card's capabilities.extensions, with the UCP release in its URI.

protocolVersion is not an A2A version

The card gives a UCP release date as its protocolVersion. A2A versions are 0.3.0 or 1.0.

FixPut the A2A version in protocolVersion and the UCP release in the extension's URI.

The card names no JSON-RPC endpoint

No url with an A2A 0.3 protocolVersion, and no supportedInterfaces entry with protocolBinding JSONRPC.

FixGive the card a JSON-RPC endpoint for 0.3, 1.0 or both.

-32008 · Extension required

The store agent requires the UCP extension and the message didn't turn it on. Inspect lets you leave the extension header out on purpose to see this.

FixSend X-A2A-Extensions (0.3) or A2A-Extensions (1.0) with the extension URI.

-32009 · Version not supported

The store agent doesn't speak the A2A version in A2A-Version.

FixPick a version the card offers.

-32001 · Task not found

The message named a taskId the store agent no longer has. The Playground drops the task and keeps the conversation (contextId).

FixKeep a task's id valid until the task reaches a final state.

See A2A: the store's agent.

Embedded failures

Embedded runs in the browser: the Playground loads the checkout's continue_url in a sandboxed frame and the store's page and the Playground exchange JSON-RPC messages over postMessage (Embedded Checkout Protocol, release 2026-08-25). Every message, and every one the Playground ignored, is on the run's trace.

The profile lists no Embedded service

The store's UCP profile has no dev.ucp.shopping entry with "transport": "embedded", so an Embedded run doesn't start.

FixAdd one, with the release's embedded.openrpc.json as its schema.

This checkout has no embedded binding

The profile lists Embedded, but the store's checkout answer has no embedded service in ucp.services with config.delegate. That checkout is redirect only: the run hands the buyer off at its continue_url and says so.

FixReturn the embedded service with config.delegate in ucp.services on every checkout that can open embedded.

No ec.ready within 15 s · the page may refuse framing (frame-ancestors)

The page never said it was ready. Most often the store's Content-Security-Policy: frame-ancestors (or X-Frame-Options) doesn't allow the Playground's origin, so the browser refused to show it. The run offers the checkout in a new tab instead.

FixList the host's origin in frame-ancestors, and send ec.ready once the page has loaded.

A message from another origin is ignored

The Playground accepts messages only from the frame it loaded and only from the continue_url's origin. A message from anywhere else is logged and not acted on.

FixServe the embedded checkout from the same origin as the continue_url.

ec.error

The store's page ended the checkout and sent ec.error with a code: abort_error, security_error, invalid_state_error, not_supported_error or timeout_error. The Playground removes the frame and offers the continue_url; the trace keeps the code, its severity and the store's words.

FixRead the code and the store's words on the trace's ec.error line.

abort_error answered to a delegated request

The buyer chose Cancel in the Playground's sheet, so the Playground answered the store's request (for example ec.payment.credential_request) with abort_error. The store's page stays open.

FixNothing is wrong with the store. Pay again from its page to get a new request.

-32601 · Method not found

The page sent a request the release doesn't define for the host. The Playground answers with a JSON-RPC error.

FixSend only the requests release 2026-08-25 defines for the host.

See Embedded: the store's checkout.

Website (WebMCP) failures

A website run opens the store's page (https:// + the domain you entered) in a browser on our side and reads the tools it registers through document.modelContext. WebMCP is not a UCP transport; these failures are about the page, not your UCP endpoint.

The page has no WebMCP (document.modelContext).

The page loaded, but document.modelContext wasn't there. The store hasn't shipped WebMCP, or only offers it on other pages.

FixRegister your tools on the page the domain opens (usually the home page). Check the public Inspector's WebMCP view: it says whether document.modelContext is present.

The page registered no WebMCP tools.

document.modelContext exists, but no tools were registered when we read it, often because tools are registered late, only after a click, or only on product or cart pages.

FixRegister your tools as the page loads, without waiting for user interaction. A store with no WebMCP tools cannot be run through its website. To follow a UCP shopping permalink, use the open_permalink tool over the store's APIs instead: a permalink is a browser link, not a WebMCP tool.

The page did not load in time

Shown as "The browser could not open the page: …" with a timeout. Very heavy pages can take too long to load in the browser. A slow load is retried once, and a page that has registered its tools by then is used anyway; the run fails only when the page still has no tools.

FixRegister tools early in page load, and reduce what has to load before they're registered.

All store-page browsers are still busy. Try again in a minute.

Every browser we run is in use. A website run waits briefly for one, and says so while it waits. The Inspector says "All browsers are still busy. Try again in a minute."

FixTry again shortly. Nothing is wrong with your store.

Also in the Inspector's WebMCP view: "That address is not a public web page." (the URL isn't a public site) and "The page could not be loaded in the browser." See WebMCP: the store page.

Automatic REST fallback

When an MCP call fails for a specific tool, the Playground automatically falls back to REST for that tool only. The fallback is per tool, not global: if search_catalog fails over MCP but create_cart succeeds, only search calls switch to REST.

Note

Error code -32603 (internal error) does not trigger REST fallback. It means MCP accepted the call but the tool itself failed, so REST would likely give the same error. Only transport-level failures like -32601 and HTTP errors trigger the switch.

Debugging steps

  1. Check Inspect — raw requests and responses, with the exact error code and message inline.
  2. Check the endpoint is reachable — use curl to confirm the endpoint is reachable and returning valid JSON-RPC.
  3. Check CORS headers — only for browser-based agents: confirm Access-Control-Allow-Origin carries the correct domain.
  4. Read the run's Trace — every tool call in order with timing. Find the failing call and whether later calls recovered.

For stores that support REST alongside MCP, see REST API fallback for the paths the Playground calls.

Something wrong on this page?