Ilya Grigorik proposes structured status fields with unrecoverable severity — enabling AI agents to make intelligent decisions about checkout failures.
When an AI agent attempts to complete a checkout and something goes wrong, what should it do? Today's UCP error responses are unstructured — a generic status code and a human-readable message. That's fine for displaying to users, but agents need more.
PR #223 introduces a ucp.status discriminator with an explicit unrecoverable severity level. This seemingly small addition has significant implications for how autonomous agents handle failures.
The core insight: Some errors are worth retrying (network glitch, temporary inventory issue), while others are terminal (product discontinued, regulatory block). Agents need machine-readable signals to distinguish between them.
The proposal adds a structured status field to UCP responses:
{
"ucp.status": {
"code": "PAYMENT_DECLINED",
"severity": "unrecoverable",
"message": "Card declined: insufficient funds",
"details": {
"retry_after": null,
"suggested_action": "request_alternative_payment"
}
}
}Key additions:
ucp.status namespace clearly identifies this as protocol-level status information, not merchant-specific data.recoverable, unrecoverable, and transient tell agents whether to retry, give up, or wait.retry_after and suggested_action provide actionable guidance.Consider these scenarios:
Agent receives: {"error": "Unable to complete checkout"}
Agent behavior: Retry? Give up? Ask user? Unknown.
Agent receives severity unrecoverable with code PRODUCT_DISCONTINUED
Agent behavior: Stop retrying, suggest alternatives, update product catalog.
This is particularly important for:
This builds on Grigorik's earlier UCP contributions:
Together, these form a coherent vision: UCP as a protocol where agents and merchants can communicate with semantic precision, not just data exchange.
The PR is open for Technical Committee review. Key questions being discussed:
suggested_action be an enum or free-form?If merged, this would likely ship in UCP's next minor version, giving agent developers a much richer vocabulary for handling checkout failures gracefully.