Retry-After

使い方

Retry-After ヘッダーは、クライアントに再試行までの待機を求める必要があるレスポンスに現れます。このヘッダーは主に次の 3 つのステータスコードと組み合わせて使われます。

このヘッダーは 2 つの形式を受け付けます。秒単位の遅延（delta-seconds）か、絶対的な HTTP-date です。秒を使う場合、値は待つべき秒数を表す非負の整数です。HTTP-date を使う場合、値は IMF-fixdate 形式に従います。

行儀のよいクライアントやクローラーは、回復途上のサーバーに負荷をかけすぎないようこのヘッダーを尊重します。

注意

検索エンジンのクローラーは、503 レスポンスの Retry-After を、ページをインデックスから削除するのではなく後で URL を再訪するためのシグナルとして扱います。Googlebot と Bingbot はいずれも、再訪のスケジューリングのためにこのヘッダーを尊重します。計画的なメンテナンスの際に 503 Service Unavailable を Retry-After とともに返すことで、インデックス可能性が維持されます。このヘッダーがないと、長時間のダウンタイムはインデックスからの削除を招くおそれがあります。

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 秒（1 時間）待つようクライアントに伝えます。

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 は両方を含めるため、クライアントはレート制限されたエンドポイントを叩き続けるのではなく、適切にバックオフできます。