Cosmos DB出现大量403 Substatus:1014写入报错该如何排查解决？

错误说明 #

你遇到的报错如下：

Response status code does not indicate success: Forbidden (403); Substatus: 1014; ActivityId: ; Reason: ();

该错误和容器预配RU、总存储占用无关，属于Cosmos DB服务端的请求负载硬限制触发的异常。

触发原因 #

• 核心触发逻辑是单个请求的有效负载总大小超过了Cosmos DB设定的2MB上限，批量写入/替换场景下大概率是单次批量请求中打包的文档总大小超出了该限制。
• 如果你使用了事务性批量（Transactional Batch）能力，即便是同一个逻辑分区下的批量操作，只要单批总负载超过2MB，也会触发该错误。
• 低概率场景下，请求携带的自定义请求头过大、文档索引字段过多导致的服务端计算后负载超限，也可能触发该错误。

解决方案 #

• 主动拆分批量请求的文档数量，根据单份文档的平均大小计算单批可容纳的文档上限，预留至少10%的冗余空间给请求元数据、索引开销，确保单批总负载低于2MB。比如单份文档平均大小为1KB时，单批请求的文档数量控制在1800份以内即可。
• 如果你使用事务性批量API，确保同一批次内的所有操作都属于同一个逻辑分区，跨分区的批量操作不要使用事务性批量API，改用普通并行批量写入，由SDK自动按逻辑分区拆分请求。
• 初始化Cosmos DB客户端时开启批量执行优化配置，比如.NET SDK设置AllowBulkExecution = true、Java SDK设置bulkEnabled = true，开启后SDK会自动对批量请求做拆分、聚合，无需手动控制单批大小即可避免超限。
• 若存在单份大小接近/超过2MB的超大文档，先对文档做业务层面的分片存储，拆分后再分批次写入，避免单个文档就触发负载上限。

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