Retry-After

用法

Retry-After 头部出现在服务器需要客户端延迟后再重试的响应中。该头部通常与三种状态码搭配使用：

该头部接受两种格式：以秒为单位的延迟（delta-seconds），或绝对的 HTTP-date。使用秒时，值为表示等待秒数的非负整数。使用 HTTP-date 时，值遵循 IMF-fixdate 格式。

行为良好的客户端和爬虫会遵循该头部，以避免压垮正在恢复的服务器。

注意

搜索引擎爬虫会将 503 响应上的 Retry-After 视为稍后重访该 URL 的信号，而非将页面从索引中移除。Googlebot 和 Bingbot 都会遵循该头部来安排回访。在计划内维护期间，返回带 Retry-After 的 503 Service Unavailable 可以保持可索引性。若没有该头部，长时间的停机可能导致被移出索引。

Delta-seconds

一个非负整数，指定客户端在重试请求前需要等待的秒数。

Retry-After: 120

HTTP-date

一个采用 IMF-fixdate 格式的绝对日期和时间，在此之后客户端可自由重试。日期使用 GMT，遵循格式 Day, DD Mon YYYY HH:MM:SS GMT。

Retry-After: Sat, 31 Oct 2026 18:00:00 GMT

示例

在维护窗口期间以 503 响应的服务器会告知客户端等待 3600 秒（一小时）后再重试。

HTTP/1.1 503 Service Unavailable
Retry-After: 3600

以 429 响应的 API 限速器会提供限速重置的绝对日期。客户端会暂停请求直到指定时间。

HTTP/1.1 429 Too Many Requests
Retry-After: Sat, 31 Oct 2026 12:30:00 GMT

带有 301 的计划重定向会包含一段延迟，以防止多个客户端立即发起重试风暴。

HTTP/1.1 301 Moved Permanently
Location: https://new.example.re/resource
Retry-After: 60

注意

API 限速器常将 Retry-After 与 RateLimit-Limit 头部搭配使用。RateLimit-Remaining 头部显示当前窗口内剩余的请求次数，而 Retry-After 则精确告知客户端在收到 429 响应后何时恢复。设计良好的 API 会同时包含两者，以便客户端优雅地退避，而不是猛烈冲击已被限速的端点。