Cosmos DB .NET SDK v3 NoSQL写入重试时机及429错误处理咨询

核心结论 #

• 429（请求速率超出限制）属于瞬时故障，但在单写入区域账户下，SDK不会自动重试Upsert这类写入操作的429错误，需要你在应用层自行实现重试逻辑。

详细说明 #

1. 429错误的属性
   Cosmos DB返回的429错误是典型的瞬时故障，它是容器当前预配吞吐量不足以支撑请求量时的临时限流措施，当请求量回落或吞吐量释放后即可正常执行。

2. SDK内置重试的限制
   v3 .NET SDK对读取、查询等幂等性操作的瞬时故障（包括429）有内置的指数退避重试逻辑，但对于单写入区域的写入类操作（如Upsert、Create、Update），因为这类操作不具备天然幂等性（重复执行可能导致数据重复、覆盖错误等非预期结果），SDK默认不会自动重试。

3. 应用层重试的实现要点

   • 确保Upsert的幂等性：只要你的Upsert操作是基于固定的id和分区键执行的，重复执行会覆盖原有文档，这种场景下Upsert是幂等的，可以安全重试。如果id是动态生成的，需要调整逻辑保证每次重试的目标文档唯一。
   • 采用指数退避策略：参考SDK内置的重试逻辑，每次重试的间隔逐步延长（比如1s、2s、4s...），避免短时间内持续触发限流。
   • 利用RetryAfter属性：捕获CosmosException后，可以通过ResponseHeaders.RetryAfter获取服务建议的重试间隔，以此来控制下一次请求的时间。
   • 拆分批量请求：将大批次的Upsert拆分为多个小批次，在批次之间加入固定延迟，从根源上降低请求速率，减少429错误的触发概率。

内容的提问来源于stack exchange，提问作者gonzaleznicolas