UCP Error Handling & Retry Logic for Resilient Commerce

The Silent Cost of Poor Error Handling in Agentic Commerce

When an AI agent executes a purchase on behalf of a user through UCP, there is no room for silent failures. A failed payment retry, a dropped inventory update, or an unhandled timeout can cascade into lost revenue, duplicate charges, or inventory mismatches. Yet most UCP implementations treat error handling as an afterthought.

Unlike traditional REST APIs where a human reviews the error message, agentic commerce requires the protocol itself to communicate failure states clearly enough for an autonomous agent to decide whether to retry, escalate, or abort. This article covers the production patterns that separate resilient UCP implementations from those that fail under load.

UCP Error Response Structure and Status Codes

UCP inherits HTTP semantics but adds commerce-specific error classification. Every UCP response includes a status code, error code, and optional retry metadata.

HTTP 2xx Success Range: Transaction completed. Agent can proceed to next step.

HTTP 4xx Client Error Range (Agent Responsibility): 400 Bad Request—malformed payload or missing required fields. 402 Payment Required—transaction rejected by issuer or payment processor. 409 Conflict—inventory race condition or duplicate order detected. 422 Unprocessable Entity—business rule violation (e.g., purchase limit exceeded, restricted product category).

HTTP 5xx Server Error Range (Retriable): 500 Internal Server Error—unexpected server fault. 502 Bad Gateway—upstream payment processor timeout. 503 Service Unavailable—rate limit or temporary outage. 504 Gateway Timeout—processing took too long.

The distinction is critical: a 4xx error requires agent logic to fix the request (revalidate inventory, adjust quantity, gather missing data). A 5xx error should trigger automatic retry with backoff.

Implementing Exponential Backoff Without Hammering Upstream Systems

A naive retry loop that hits the server every 100 milliseconds will accelerate the very outage it’s trying to survive. UCP implementations must follow a controlled backoff strategy.

Standard Pattern: Wait = (2 ^ attempt) + random(0, 1) seconds, capped at max_backoff (typically 60 seconds). Attempt 1: ~1 second. Attempt 2: ~3 seconds. Attempt 3: ~7 seconds. Attempt 4: ~15 seconds. The jitter (random component) prevents thundering herd problems when multiple agents retry simultaneously.

Most UCP implementations should retry 5xx errors no more than 3–5 times before failing the transaction and alerting the merchant. A 503 response may include a Retry-After header; respect it and use it to set the backoff floor.

Example scenario: A payment processor temporarily loses connectivity. First agent retry happens at 1 second. By the time attempt 3 fires at ~7 seconds, the processor has often recovered. Attempting 10 times with 100ms delays would waste 1 second of total time but create 10x the load.

Idempotency: Preventing Double Charges and Duplicate Orders

In distributed systems, a response timeout does not mean the transaction failed—it means you don’t know if it succeeded. An agent that retries without idempotency protection will charge the user twice.

UCP requires merchants to accept an optional Idempotency-Key header on order creation endpoints. This key (typically a UUID generated by the agent) allows the merchant to deduplicate requests. If the same key is submitted twice, the server returns the original response without processing the order again.

Implementation requirement: The merchant must persist the Idempotency-Key and its associated response for at least 24 hours. When a retry arrives with the same key, the server looks up the cached response and returns it immediately—without re-authorizing the payment or decrementing inventory.

Agents must generate and store the Idempotency-Key before submitting the order. If the network fails or the response times out, the agent retries with the same key. The merchant deduplicates and returns the original result. No double charge.

Handling Partial Failures and Cascading Errors

A single transaction often involves multiple UCP calls: validate inventory, reserve stock, authorize payment, create shipment. If the second call fails, the agent must handle rollback or compensation.

Scenario: Agent validates inventory (passes), authorizes payment (passes), but the shipment creation call returns 503 (Service Unavailable). The payment is already charged. The inventory is reserved. But no fulfillment record was created.

Correct pattern: The agent should retry the shipment creation with exponential backoff. If it eventually succeeds, the transaction completes normally. If max retries are exhausted, the agent logs a critical alert (not an error) and marks the order as requires-manual-fulfillment. A human merchant then reviews the order, verifies payment cleared, and manually creates the shipment in their fulfillment system.

Never allow an agent to automatically reverse a payment without explicit merchant approval. Payment reversals (refunds) are themselves UCP calls that can fail. Rollback logic must be transactional or compensatory, not automatic.

Circuit Breakers: Protecting Against Cascading Failures

If an upstream service (payment processor, inventory system) is down, the agent should stop hammering it after a few failed attempts. A circuit breaker pattern prevents this.

How it works: Track the failure rate for a specific endpoint. Once failures exceed a threshold (e.g., 5 consecutive 5xx errors), the circuit breaker “opens”—subsequent requests immediately fail without calling the endpoint. After a timeout (e.g., 30 seconds), the circuit transitions to “half-open” and allows a single probe request. If that succeeds, the circuit closes and normal traffic resumes. If it fails, the circuit opens again.

This pattern prevents agents from wasting compute and time on calls that will fail. It also gives downstream services breathing room to recover.

Logging and Observability for Failed Transactions

Every error must be tagged with: request ID (from UCP response headers), timestamp, error code, attempted retries, agent ID (or user ID), and final outcome (success after retry, failed, manual review required).

Aggregate these logs by error code and merchant. If a specific merchant’s payment authorizations suddenly spike in 402 errors, that is usually a card-issuing bank flagging fraud. If a merchant’s inventory endpoints return 500, their ERP may be failing. Visibility into these patterns is how merchants catch and resolve problems before customers notice.

FAQ: UCP Error Handling

Q: Should agents retry 4xx errors? No. A 400 (bad request) or 422 (unprocessable entity) indicates the agent’s logic is wrong, not the server. Retrying will produce the same error. The agent should log the error, notify the merchant, and ask the user to modify their request (e.g., enter a valid address, choose a different payment method).

Q: What if the merchant’s Idempotency-Key cache expires? If the agent retries after 24 hours and the merchant has purged the cache, the order may process twice. To avoid this, agents should not retry order creation after 6 hours; instead, they should query the order status API to check if the order exists.

Q: Can I set backoff to a fixed delay, e.g., 1 second every time? You can, but fixed delays don’t scale. With 100 agents all retrying at 1-second intervals, they will create synchronized load spikes. Exponential backoff with jitter spreads retries across time and reduces peak load.

Q: How do I handle timeouts differently from 5xx errors? A timeout is a network-level failure, not an HTTP error. It should trigger the same retry logic as a 5xx: exponential backoff, idempotency, and eventual escalation if max retries are exceeded.

Q: Should I retry DELETE operations (e.g., cancel order)? Yes, with the same idempotency logic. A DELETE request should include an Idempotency-Key. If the cancellation succeeds, the key is cached. If retried, the merchant returns the cached response (order was already cancelled) without processing again.

Q: What is the difference between a timeout and a 504 Gateway Timeout? A timeout occurs when the agent never receives a response (network black hole). A 504 means the server received the request, tried to process it, and failed to respond in time. Both should trigger retry. A 504 is slightly preferable because the server acknowledges the attempt; a true timeout leaves uncertainty about whether the request reached the server at all.

Production Checklist for UCP Error Resilience

Implement exponential backoff for 5xx errors with jitter (2^attempt + random, capped at 60s). Generate Idempotency-Key before order submission and store it alongside the response for ≥24 hours. Log all errors with request ID, error code, retry count, and outcome. Implement circuit breakers for endpoints that exceed 5 consecutive failures. Query order status API instead of retrying CREATE after 6 hours. Never auto-reverse payments; escalate to merchant. Monitor error rates by error code and merchant to detect systemic issues. Test retry logic with chaos engineering (inject 5xx responses, timeouts, partial failures) in staging before production rollout.