UCP Rate Limiting: How to Build Agents That Respect Merchant API Limits

One of the fastest ways to get an agent banned from a merchant’s UCP endpoint is to ignore rate limits. Agents that hammer merchant APIs — whether through polling loops, retry storms, or poorly structured batch operations — create real operational problems for merchants and ultimately for the humans trying to use them. UCP’s rate limiting specification is designed to make it easy for well-behaved agents to stay within limits and for merchants to communicate their limits clearly. See also: UCP SDKs & Libraries. See also: UCP SDKs and Client Libraries. See also: UCP API Quickstart. For related reading, see Merchant’s Playbook for UCP Adoption. For related reading, see Implementing UCP Agent Authentication. For related reading, see Common UCP Integration Errors and How to Debug Them.

UCP Standard Rate Limit Headers

Every UCP endpoint response includes standardized rate limit headers: X-UCP-RateLimit-Limit (the total requests allowed in the current window), X-UCP-RateLimit-Remaining (requests remaining in the current window), X-UCP-RateLimit-Reset (Unix timestamp when the window resets), and X-UCP-RateLimit-Retry-After (seconds to wait before retrying after a 429 response). These headers are mandatory for all UCP-certified merchants. An agent that reads and respects these headers will never be rate limited under normal operating conditions.

Agent Implementation: Reading Rate Limit Headers

A well-implemented UCP agent tracks rate limit state per merchant endpoint. Before each request, the agent checks whether sufficient quota remains in the current window. If quota is nearly exhausted, the agent either waits for the window to reset or defers the request to a lower-priority queue. After receiving a 429 response, the agent must respect the Retry-After header and not retry before the specified delay. Agents that retry immediately after a 429 are violating the UCP specification and may be suspended from the merchant’s endpoint.

Batch Operations and Rate Limit Management

Catalog fetches, order status updates, and inventory checks are often most efficiently handled as batch operations. UCP provides batch endpoints for these operations specifically to reduce the per-operation request count that would accumulate from individual calls. Agents should use batch endpoints wherever available and structure their batch operations to stay within a single rate limit window rather than splitting them in ways that require multiple window resets.

Burst vs. Sustained Rate Limits

UCP merchants may configure both burst limits (maximum requests in a short window, typically 1 minute) and sustained limits (maximum requests per hour or day). Agents handling time-sensitive transactions like flash sales or limited inventory purchase windows need to understand both limits. Burst limit design should account for the maximum legitimate concurrent demand the agent will generate, not just average demand.

Frequently Asked Questions

What should an agent do when it receives a 503 from a UCP merchant endpoint?

503 indicates a temporary service unavailability, not a rate limit. The agent should implement exponential backoff starting at 1 second and retry for up to 5 minutes. If the 503 persists beyond 5 minutes, the agent should log the failure, notify the monitoring system, and defer the transaction rather than continuing to retry.

Frequently Asked Questions