# 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:

```json
{
  "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:

```json
{
  "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.