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.