When your application exceeds the provisioned Request Units per second allocated to a Cosmos DB container, the service returns an HTTP 429 error. This response signals that requests are being throttled to protect system availability.
Common Causes of Throttling
Throttling usually stems from sudden traffic spikes, inefficient cross-partition queries, or poorly distributed partition keys leading to localized hot spots. While short bursts are normal, persistent 429 errors mean your system needs client-side retry tuning or scaled throughput.
Configuring Client SDK Retry Options
The Azure SDKs automatically retry throttled requests, but default values might not suit high-throughput background processing jobs. You can explicitly customize retry attempts and wait times during client initialization:
// Configure custom retry settings to gracefully handle throughput spikes
CosmosClientOptions clientOptions = new CosmosClientOptions()
{
// Increase maximum retry attempts beyond the default value of 9
MaxRetryAttemptsOnThrottledRequests = 15,
// Set maximum accumulated wait time for retries to 30 seconds
MaxRetryWaitTimeOnThrottledRequests = TimeSpan.FromSeconds(30)
};
// Instantiate the client with adjusted resilience options
CosmosClient client = new CosmosClient("ACCOUNT_ENDPOINT", "ACCOUNT_KEY", clientOptions);If increasing retry parameters does not clear the 429 responses, consider switching container throughput to autoscale mode or converting low-traffic workloads to serverless capacity.
HTTP 429 in Azure Cosmos DB means a request was throttled because it exceeded the available request units (RUs) for the affected resource or partition. It can happen during traffic spikes, but repeated 429s may point to a capacity or workload issue that needs attention.
A 429 is not always a failed operation. The Azure Cosmos DB SDKs automatically retry throttled requests, using the service's retry-after delay. Check the SDK response and diagnostics before adding your own retry loop; immediate retries can send more traffic while the service is asking the client to wait.
Find out where the throttling is coming from
Start with Azure Monitor metrics and request diagnostics. Look at throttled requests alongside RU consumption, request volume, latency, and the affected database or container. In particular, check normalized RU consumption and whether throttling is concentrated on a partition rather than spread across the container.
If traffic is uneven, one logical partition may be receiving a disproportionate share of requests. That hot logical partition can run out of available throughput even when the container appears to have capacity overall. Review the partition key and the distribution of reads and writes; a key that groups most activity under one value may need a different data model.
Reduce avoidable RU use or add capacity
When you do handle retries yourself, respect the server-provided retry-after delay and use bounded retries with backoff. Avoid retrying indefinitely, and distinguish a request that the SDK eventually completed from one that exhausted its retry budget. That makes it easier to tell normal short-lived throttling from a sustained capacity or partitioning problem.