HTTP 429 Request Rate Too Large during Cosmos DB write retries

Write Idempotency in Azure Cosmos DB

When implementing high-throughput write operations in Azure Cosmos DB, the SDK automatically handles transient failures, such as HTTP 429 (Request Rate Too Large), by retrying the request based on the x-ms-retry-after-ms header.

A critical design concern is ensuring that these retries do not result in duplicate records or unintended data overwrites when the initial request may have actually succeeded on the server despite a timeout or connectivity failure returning to the client.

While the Upsert operation and the use of a consistent id property provide a mechanism for idempotency, the behavior differs when integrating these with optimistic concurrency controls using ETags.

• How does the SDK handle retry logic when a write operation fails with a 429 but the server-side state has already been updated?
• What is the impact on idempotency when combining Upsert with If-Match headers during an automatic retry cycle?