UCP Error Reference

version_unsupported

Cause

• Agent is using an older or newer protocol version than the merchant supports
• Merchant has not set up supported_versions for backward compatibility
• Typo in version string (must be YYYY-MM-DD format)

Error Response

{
  "ucp": { "version": "2026-01-11", "status": "error" },
  "messages": [{
    "type": "error",
    "code": "version_unsupported",
    "content": "Version 2026-01-12 is not supported. This business implements version 2026-01-11.",
    "severity": "unrecoverable"
  }],
  "continue_url": "https://merchant.com/"
}

Fix

• Agent side: Check the merchant's /.well-known/ucp profile for their current version. Update your client to match.
• Merchant side: Add the agent's version to supported_versions with a version-specific profile URI, or upgrade your implementation.

capability_not_supported

Cause

• Agent requested a capability the merchant does not advertise in their profile
• Capability was removed in a newer protocol version
• Namespace mismatch (e.g. requesting dev.ucp.shopping.loyalty when the merchant only supports dev.ucp.shopping.checkout)

Fix

• Check /.well-known/ucp for the merchant's advertised capabilities
• Use capability negotiation: only request capabilities in the intersection
• If you need a capability the merchant does not have, escalate to the merchant or use a fallback flow

requires_escalation

Cause

• 3D Secure authentication required by the payment handler
• Address selection needed (multiple shipping addresses on file)
• Final-sale or pre-order confirmation required
• Payment instrument requires additional verification

Response

{
  "status": "requires_escalation",
  "continue_url": "https://merchant.com/checkout/chk_xyz/verify"
}

Fix

• Present the continue_url to the buyer
• Buyer completes the step in their browser
• Poll the checkout status or wait for webhook to resume

invalid_profile

Cause

• /.well-known/ucp returns invalid JSON
• Required fields missing from the profile (e.g. version, services)
• Spec URL does not match namespace authority (e.g. dev.ucp.* capability pointing to non-ucp.dev URL)
• Profile contains a non-date version string (e.g. "draft")

Fix

# Validate your profile structure
curl -s https://your-store.com/.well-known/ucp | jq .

# Check required fields exist
curl -s https://your-store.com/.well-known/ucp | \
  jq '{version: .ucp.version, services: (.ucp.services | keys), capabilities: (.ucp.capabilities | keys)}'

# Verify spec URLs match namespace
curl -s https://your-store.com/.well-known/ucp | \
  jq '.ucp.capabilities["dev.ucp.shopping.checkout"][0].spec'
# Must start with https://ucp.dev/

schema_resolution_failed

Cause

• Extension schema URL is unreachable or returns 404
• Extension $defs key does not match parent capability name
• requires constraints not satisfied by negotiated versions
• Circular dependency between extensions

Fix

• Verify all schema URLs in your profile return 200 with valid JSON
• Check that each extension's $defs has an entry matching every parent in extends
• Check requires constraints against your declared versions
• Use the schema resolution flow: Discovery > Negotiation > Schema Fetch > Version Compatibility > Compose > Validate

payment_handler_error

Cause

• Payment processor (Stripe, Adyen, etc.) returned an error
• Payment instrument token is invalid or expired
• AP2 mandate is missing or invalid
• Currency mismatch between checkout and payment instrument

Fix

• Check your payment handler's dashboard for the underlying error
• Verify AP2 mandate is correctly formatted and signed
• Ensure the payment instrument token is fresh (not expired)
• Check that the currency in the checkout matches what the payment handler expects

checkout_expired

Cause

• Checkout session has exceeded its time-to-live (typically 15-30 minutes)
• Agent took too long between checkout creation and completion

Fix

• Create a new checkout session from the cart
• Implement checkout status polling to detect expiration before attempting completion
• If long conversations are expected, create the checkout late in the flow (only when buyer confirms intent to purchase)

namespace_mismatch

Cause

• A dev.ucp.* capability has a spec or schema URL not on ucp.dev
• A com.example.* capability has a spec URL not on example.com

Fix

Ensure spec and schema URLs match their namespace authority:

CORS / Cross-Origin Errors

Symptom

Agent gets a CORS error when fetching /.well-known/ucp or making API calls. Browser console shows "Access-Control-Allow-Origin" errors.

Cause

• Merchant's server is not sending Access-Control-Allow-Origin header
• Preflight requests (OPTIONS) are not handled

Fix

# nginx: add CORS headers to UCP endpoints
location = /.well-known/ucp {
    default_type application/json;
    add_header Access-Control-Allow-Origin *;
    add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS";
    add_header Access-Control-Allow-Headers "Content-Type, UCP-Agent";
}

location /api/ucp/ {
    add_header Access-Control-Allow-Origin *;
    add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS";
    add_header Access-Control-Allow-Headers "Content-Type, UCP-Agent";
    
    if ($request_method = OPTIONS) {
        return 204;
    }
}

Need More Help?