处理速率限制和服务器错误
收到 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 的值。自动重试应限定为少量次数,达到上限后停止并报告故障,以便检查。