Diagnosing Azure Cosmos DB SQL API RU Throttling and 429 Errors

The problem: your application is receiving 429 errors

Azure Cosmos DB SQL API containers are provisioned with request units per second (RU/s), which represent the throughput budget for reads, writes, and queries. When a request would consume more RUs than remain available in that second, the service returns HTTP 429 Too Many Requests. The client sees failures or elevated latency, and the response includes a retry-after header telling the caller how long to wait.

Useful takeaway: do not simply increase throughput. First confirm whether throttling comes from insufficient provisioned capacity, an uneven partition key distribution, or an expensive consistency setting, then apply the matching fix.

Scope note: this guide covers the SQL API. Other Cosmos DB APIs, such as MongoDB or Cassandra, may surface throttling through different signals.

Recognizable condition

• HTTP 429 responses from the Cosmos DB SDK or REST API.
• Response header x-ms-retry-after-ms present with a wait time in milliseconds.
• Azure Monitor shows Throttled Requests greater than zero while Total Request Units approaches the provisioned limit.
• Latency spikes affect only some partition key values, suggesting a hot partition.

Cause and diagnostic table

Observation	Likely cause	Where to check
429 errors across all partition keys; Total Request Units near 100% of provisioned RU/s	Provisioned throughput is too low for the workload	Azure Monitor metrics; container scale settings
429 errors concentrated on a few partition key values; one partition shows high RU consumption	Partition key skew or hot partition	Azure Portal > Data Explorer > Partition Key Distribution
Higher-than-expected RU charge per read or write	Strong or bounded staleness consistency, or large item size	SDK request diagnostics; account consistency setting
Throttling appears after enabling multi-region writes or during regional failover	Cross-region replication and write propagation	Account replication settings; region-specific metrics

Ordered checks

1. Confirm throttling in Azure Monitor

   Open the Cosmos DB account in the Azure portal, select Metrics, and add Total Request Units and Throttled Requests. Set the time grain to one minute. If Throttled Requests is non-zero while Total Request Units reaches the provisioned RU/s ceiling, the container is being throttled by capacity.

   Expected check: the Throttled Requests chart shows spikes aligned with application errors.

2. Inspect SDK request diagnostics

   Enable request diagnostics in the SDK client options. In the .NET SDK, response diagnostics include the status code and retry-after value. Capture this in application logs during a throttling event.

   Where to run: application code that calls the Cosmos DB SDK. Permissions: data plane access to the container, read or write depending on the operation.

   Expected check: status code 429 and a non-null retry-after header. Risk: logging every retry-after value at high volume can produce noisy logs; sample them.

3. Check partition key distribution

   In the Azure portal, open Data Explorer, select the container, and view the Partition Key Distribution chart. Look for one logical partition consuming a disproportionate share of storage or RUs.

   Expected check: a flat distribution means throughput is spread evenly; a spike on one key means a hot partition.

4. Review consistency level and operation size

   Check the account's default consistency level and any per-request consistency override. Strong consistency consumes more RUs per operation than session or eventual consistency. Also inspect item size; large items cost more RUs to read or write.

   Expected check: if RU charge per operation is high and consistency is set to Strong, consistency is a contributing factor.

5. Review multi-region write configuration

   If the account has multiple write regions, confirm whether writes are being issued to more than one region simultaneously. Multi-region writes replicate data across regions and can contribute to RU consumption and replication latency.

   Expected check: throttling correlates with write traffic across regions rather than a single region.

Fixes tied to findings

If provisioned throughput is too low

Increase manual throughput or switch to autoscale. For manual throughput, use the Azure CLI. Replace the placeholders with your account, resource group, database, container, and desired RU/s.

az cosmosdb sql container throughput show \
  --account-name 'my-cosmos-account' \
  --resource-group 'my-rg' \
  --database-name 'my-database' \
  --container-name 'my-container'

To update:

az cosmosdb sql container throughput update \
  --account-name 'my-cosmos-account' \
  --resource-group 'my-rg' \
  --database-name 'my-database' \
  --container-name 'my-container' \
  --throughput 5000

Where to run: a terminal with Azure CLI installed and logged in. Permissions: Microsoft.DocumentDB/databaseAccounts/throughput/write on the account. Risk: increasing RU/s raises hourly cost immediately; decreasing it can reintroduce throttling.

Practical check: after the change, monitor Total Request Units and Throttled Requests for at least 15 minutes.

If a hot partition is causing throttling

Change the partition key to a property with higher cardinality and more even write distribution. Existing containers cannot have their partition key changed in place; you must migrate data to a new container with a different key, typically using the Azure Cosmos DB change feed or bulk executor.

As an interim mitigation, reduce request frequency for the hot key or cache read-heavy hot items in the application layer.

Practical check: reopen Partition Key Distribution after migration and confirm the top partition no longer exceeds its proportional share.

If consistency or item size drives RU cost

Lower the consistency level for operations that do not require Strong consistency, for example to Session or Consistent Prefix. Verify application correctness before deployment because weaker consistency changes read-your-writes and ordering guarantees.

For large items, consider breaking documents into smaller related items or compressing content where appropriate.

Practical check: compare SDK request diagnostics RU charge before and after the consistency change for the same operation.

If multi-region writes contribute to spikes

Route writes to a single write region when possible, or enable autoscale to absorb replication-related RU variation. Review the account's regional configuration and failover priorities.

Practical check: compare Throttled Requests per region in Azure Monitor after routing changes.

Escalation criteria

Engage Azure support if:

• Throttling persists after provisioned throughput exceeds observed peak RU consumption by a comfortable margin.
• You cannot identify a hot partition, but 429 errors continue on all keys.
• SDK diagnostics do not include retry-after headers despite 429 responses, suggesting a client or network interception issue.
• You need to change the partition key on a production container and require guidance on zero-downtime migration.

Limitations and verification

Autoscale can absorb bursts but may result in higher maximum RU/s charges during peaks. Review the autoscale max RU setting and cost estimates before enabling it.

The Cosmos DB Emulator can simulate RU patterns for development workloads, but it does not perfectly replicate multi-region replication or production throughput behavior.

Verify any throughput or consistency change in a non-production container first. Confirm the result by checking Azure Monitor metrics and SDK diagnostics under a representative load. Portal navigation and CLI parameter names may change; check the current command reference before running updates in production.