Agent 批量读文档遇到 429：怎样停止重试风暴并保住读取进度
批量读取文档时，一个 worker 收到 429 后开始等待，其他 worker 却继续发请求，重试也陆续醒来。这时，单条请求遵守了退避规则，整批任务仍可能持续冲击同一额度。接入方需要让共享额度范围内的请求一起等待，并在本轮截止前保存进度，使任务可以有边界地结束和恢复。
先确定哪些请求需要一起停
RFC 6585定义 429 表示一定时间内请求过多，但不规定服务端如何识别调用者、统计请求或划分额度；Retry-After也是可选响应头。因此，不能从一个 429 推断“每位用户都有独立额度”。
开始批处理前，先确认接口的限流范围、SDK 是否自动重试，以及本轮任务的截止时间和尝试上限。范围可能与应用、租户或接口类型有关，应以实际服务文档为准。范围不明时先暂停本次批任务并确认，不通过更换身份或增加应用绕过限制。
建议把同一已确认额度范围交给共享调度器，统一维护最早允许发送时间、并发数和发送节奏。任一请求遇到 429，就更新这个范围的等待状态，暂停新分发和重试；多个等待提示取更晚的时间，不能被另一条较短提示覆盖。跨进程或多机器执行时也要共享状态，单个进程里的信号量管不到其他机器。
这有具体产品依据：SharePoint Online 官方文档要求在重试或发送新请求前遵守等待时间，并说明被限流的请求仍计入使用量。这是该产品的规则；其他服务需逐一核实，不能照搬额度。
等待多久，与这一轮还能等多久，分别决定
RFC 9110规定，Retry-After可以是 HTTP 日期，也可以是收到响应后应等待的非负整数秒。接入时需分别解析，并检查时钟偏差；供应商自定义的 reset 字段不能擅自按同一格式或单位解释。
缺少有效提示时，才按事先确认的策略执行有次数和时长上限的退避。存在有效服务端等待时，本地退避上限和随机抖动不能让请求提前发出。到点后也应按受控节奏恢复，避免所有 worker 同时醒来，再形成一次尖峰。
若最早允许发送的时间已经到达或超过本轮截止，就保存剩余清单并结束这一轮。不能为了赶截止而缩短服务端等待；截止已到或尝试次数耗尽，也应停止新分发，保留停止原因。需要继续时由新一轮明确接续，但不能通过重启清空原有等待和累计尝试记录。
还要选定一个负责重试的层，并统计真正发出的底层请求。AWS 关于超时、重试与抖动的架构文章指出，多层独立重试会相乘放大负载。外层任务、SDK 和网关各自重试时，界面上的“一次读取”可能已经产生多次请求。这是架构经验，不是其他产品的服务承诺。
把恢复位置存下来，别只存一条报错
台账至少分开记录文档稳定 ID 与版本、完成状态及结果引用、实际尝试次数、下一次允许发送时间、本轮截止、剩余待办和停止原因。共享额度范围的等待状态也要落盘，不能只藏在某个 worker 的内存里。台账限制访问，不写访问令牌、带凭证的下载链接或整篇敏感正文。
只有结果完整接收并保存，才标记该项完成。“请求已经发出”不算完成。取消时先阻止新分发，对已经在途的请求另行确认结果；重启后核对结果与台账，只接续未完成项，并重新检查权限和文档版本。版本发生变化时，重新分批或单列变化项，不能把不同版本拼成同一批快照。
批量接口还可能需要逐项判断。例如，Microsoft Graph 的 JSON batch外层可返回 200，子请求却分别返回 429，而且 SDK 不会自动重试这些批内失败项。该文档建议可按失败项中最长的等待时间，重新提交失败项。不能据外层成功标记整批完成，也不必把已完成项整批重做；这是 Graph 的特定约定。
用合成响应验收，观察真正的发送与恢复
在本地替身接口中构造 429 和成功响应，记录实际发送时刻、尝试次数和持久台账，按下表检查。这是一组待执行的验收方法，不代表已经完成供应商接口测试。
| 构造的情形 | 应观察到的结果 |
|---|---|
| 秒数、HTTP 日期及缺失或非法等待提示 | 有效等待不会被本地上限截短；无有效提示时走约定的有界退避。 |
| 多个 worker 共用额度 | 收到 429 后，同范围的新分发与重试均停止；恢复时没有同时集中发送。 |
| 持续 429、等待越过截止或尝试耗尽 | 任务有明确结束状态，剩余清单可读；没有无限等待或抢在服务端允许前发送。 |
| 取消后重启，或保存结果时中断 | 等待与累计次数仍在；已确认保存的结果不重读，未完成项和在途结果经核对再接续。 |
| 批内部分失败，且 SDK 开启重试 | 逐项记录结果，已完成项不重复提交；底层实际尝试符合指定重试层的预算。 |
将等待与恢复约定带进文档接入评估
石墨文档中台（Office SDK）面向已有业务系统提供文档预览、编辑、转换与协作能力。具体读取接口、限流范围、等待提示、SDK 重试和断点支持，需要按实际版本与项目方案确认，不能由上述其他厂商的规则推定。
准备目标接口、批量规模、本轮可接受的截止时间和恢复台账要求，再预约演示，与接入团队明确服务端约定、客户端调度责任和验收分工。
在企业文档中验证
需要在自己的环境中验证时，可先了解私有化部署方案，再确定试用范围与验收要求。