调用 VTEX API 时优雅处理限流：指数退避…

在构建任何调用 VTEX API 的集成（目录同步、订单处理、价格/库存更新、履约）时，用指数退避加抖动、尊重 Retry-After、熔断器和请求队列来优雅应对 429 限流，避免数据丢失和性能下降。

适用场景

解决思路

1. 对所有 429 响应实现指数退避加抖动，公式为 delay = min(maxDelay, baseDelay * 2^attempt) * (0.5 + random(0, 0.5))。
2. 在 429 响应上始终读取 Retry-After 头，并取 Retry-After 值与计算出的退避延迟中的较大者作为等待时间。
3. 当服务持续失败（例如连续 5 次失败）时启用熔断器，防止级联失败并给服务恢复时间。
4. 使用请求队列控制吞吐量，避免突发流量触发限流。
5. 在成功响应上主动监控 X-RateLimit-Remaining，在触发 429 之前就主动降速。
6. 了解 VTEX 各 API 的限流差异：Pricing API 的 PUT/POST 为每账户 40 请求/秒、1000 突发额度，DELETE 为每账户 16 请求/秒、300 突发额度；Catalog API 因端点而异、无公开固定限制；Orders API 受平台通用限制，VTEX 建议 429 时退避 1 分钟。
7. 理解突发额度（Burst Credits）机制：超出限流时每个超额请求消耗 1 个额度，额度耗尽后请求被 429 阻断；路由未被使用时额度按该路由限流速率随时间回填。
8. 解析并使用限流响应头：Retry-After（429 响应中需等待的秒数）、X-RateLimit-Remaining（当前窗口剩余请求数）、X-RateLimit-Reset（限流窗口重置的时间戳，单位秒）。
9. 禁止使用 while(true) 重试循环，禁止使用小于 5 秒的 setInterval/setTimeout 轮询 VTEX API。
10. 轮询时使用受控间隔（例如至少 30 秒），并在遇到 429 时按 Retry-After 等待后再继续。
11. 封装一个限流感知的 HTTP 客户端，自动带上重试逻辑，默认 maxRetries: 5、baseDelayMs: 1000、maxDelayMs: 60000。
12. 实现熔断器状态机：CLOSED（正常放行）、OPEN（失败后阻断请求）、HALF_OPEN（放行一个测试请求），默认连续 5 次失败后打开、30 秒后进入半开、半开下连续 3 次成功后关闭。
13. 实现请求队列按 requestsPerSecond（例如 10）节流，并在队列中通过熔断器执行每个请求。
14. 解析限流头做主动降速：当 X-RateLimit-Remaining 低于 10 时增加额外延迟（例如 2 秒），低于 5 时显著降速（例如 5 秒），低于 20 时适度降速（例如 1 秒），否则正常速度（例如 100 毫秒）。
15. 避免固定重试延迟（如总是 5 秒）而不加抖动，否则会造成惊群效应，所有被限流客户端同时重试再次触发限流。
16. 不要只被动处理 429，而应在成功响应上监控 X-RateLimit-Remaining 主动降速，因为收到 429 时已经损失了突发额度。
17. 按审查清单自检：是否实现指数退避加抖动、是否读取并尊重 Retry-After、是否存在紧凑重试循环、是否有熔断器、是否主动监控 X-RateLimit-Remaining、是否使用正确阈值（maxRetries: 5、baseDelayMs: 1000、maxDelayMs: 60000）、是否遵守 Pricing API 限流（PUT/POST 40 req/s、DELETE 16 req/s、突发额度）。

适用边界 · 注意事项

• 不要用于目录同步的特定逻辑（参见 marketplace-catalog-sync）。
• 不要用于订单事件消费与处理（参见 marketplace-order-hook）。
• 不要用于发票与物流跟踪提交（参见 marketplace-fulfillment）。