跳至内容

处理速率限制和服务器错误

收到 429 响应后退避等待,并在临时服务器故障后谨慎重试安全的操作。

更新于

处理 429 响应

受速率限制的请求会返回 429 Too Many Requests,其中 detail.status 为 rate_limit_exceeded。重试前请检查响应头:

  • Retry-After 表示被拒绝请求至少应等待的秒数。
  • X-RateLimit-Limit 表示限流桶的上限。
  • X-RateLimit-Remaining 表示剩余可用请求数。
  • X-RateLimit-Reset 表示限流桶的重置时间。

先等待 Retry-After 指定的时间,再使用指数退避和随机抖动重试。减少并行请求,并将任务排队,不要在时间窗口重置后立即集中发送大量请求。

处理服务器错误

对于 500 响应,公开响应体包含一般性错误和 request_id,不会返回内部异常详情。503 可能表示所需服务暂时不可用。

对只读请求使用有上限的退避重试。在重试创建、更新、支付或其他改变状态的请求前,先确认第一次尝试是否已完成。超时或 5xx 响应不能证明操作失败,立即重试可能造成重复操作。

保留诊断信息

记录时间戳、方法、路径、状态、响应体和 X-Request-Id。切勿记录 x-api-key 的值。自动重试应限定为少量次数,达到上限后停止并报告故障,以便检查。