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-04-08",
    "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-04-08",
    "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.

Webhooks (orders)

When the order capability is enabled in the future, merchants will be able to subscribe to order lifecycle events. Outbound webhooks will be signed with JWS (ES256). Public verification keys will appear in the signing_keys array of the discovery profile.