Responses & Errors

Every UCP REST response includes protocol metadata. Agents should inspect the ucp block and messages array on every call.

Success envelope

Successful REST responses are JSON objects that include a top-level ucp block:


{
  "ucp": {
    "version": "2026-08-25",
    "status": "success",
    "capabilities": { }
  }
}

Resource fields (products, id, line_items, etc.) sit alongside this block.

Error envelope

Errors return an appropriate HTTP status (4xx/5xx) with:


{
  "ucp": {
    "version": "2026-08-25",
    "status": "error"
  },
  "messages": [
    {
      "type": "error",
      "code": "validation_error",
      "content": "Human-readable description",
      "severity": "recoverable"
    }
  ]
}

Common error codes

Code	Description
`unauthenticated`	Missing or invalid credentials
`tier_denied`	Authentication tier not allowed for this resource
`rate_limited`	Rate limit exceeded
`validation_error`	Invalid request payload
`cart_not_found`	Cart ID does not exist
`product_not_found`	Product or variant ID does not exist

Severity

The severity field hints at whether the agent can retry or must escalate to a human:

recoverable — agent may retry or adjust the request
unrecoverable — agent should stop and report the error
requires_buyer_input — agent needs user intervention

Rate limiting

Requests are rate-limited per authentication tier and resource bucket (catalog, cart, checkout, order). Limits vary by tier — token-authenticated agents receive the highest quotas; anonymous agents receive the lowest.

When rate limited, the API returns 429 with a rate_limited error. Responses include standard rate-limit headers indicating remaining quota and reset time.

Order notifications and signing keys

The release profile advertises the order capability and publishes public signing keys in the top-level keys array. Follow the order specification and the store’s advertised schemas for supported lifecycle notifications and verification requirements.

UCP order notifications are separate from Events in Work Hub, which trigger Workers and Playbooks, and from Admin REST webhooks, which notify external applications.