私たち開発者は、自社サービスを開発する中で、機能拡張やデータ連携のためにさまざまな外部 Web サービスや SaaS の API を利用する機会が数多くあります。
その際、API からの応答が常に正常（200 OK）であるとは限りません。相手のサーバー負荷が高かったり、こちらの利用回数が API のレートリミット（単位時間あたりの利用上限）を超えてしまったりすると 429 Too Many Requests のようなエラーが返ってきます。
このような時、ユーザーに余計な操作をさせずに自動的に再試行（リトライ）するような設計が多くの場面で求められますがあまり時間をおかずにリトライをしてしまうと再度同じエラーが返ってくるだけでなくサーバーの負荷をより高めてしまう懸念があります。
ではどれくらい時間をおいてからリトライするのが望ましいのか、といった悩ましい課題を解決してくれる HTTP ヘッダーが「 Retry-After 」です。
「Retry-After」ヘッダーとは？
「Retry-After」は、クライアントが「次にいつリクエストを再試行すべきか」のタイミングをサーバー側から指示するための HTTP レスポンスヘッダーです。
時間の指定方法によって以下の 2 つの形式があります。
- Retry-After: Wed, 01 Apr 2026 12:45:10 GMT
※ 世界標準時の 2026/4/1 12:45:10（日本時間の 2026/4/1 21:45:10）以降にリトライしてください。 - Retry-After: 120
※ 120 秒後以降にリトライしてください。
リトライの間隔を決める方法としては「 指数バックオフ 」というクライアント側でリトライごとに待ち時間を指数関数的に増やしていくようなアルゴリズムもよく利用されますがサーバー側でリソースが利用可能になる正確な時刻が分かっている場合や、クライアントごとに公平にアクセスするタイミングをサーバー側で制御したい場合などには Retry-After ヘッダーを利用することで効率的なリトライを促すことが可能となります。
特にSaaSで提供されるWeb APIにおいては多くの場合、時間当たりの呼び出し回数に制限（レートリミット）がありそれを超過した場合にはRetry-Afterヘッダーが指定されることもありますので、指定された値に応じた待機を行ってからリトライを行うようにすることが大切です。
また逆にサーバー側の開発でWeb APIを提供する場合にも同様で、クライアントから無用なリトライをさせないことでサーバーの負荷を低減することにもつながりますのでうまく活用できればと思います。
なお Retry-After ヘッダーは上記のようなレートリミット超過時のリトライ間隔の調整だけでなく 以下のような場面でも使用されます。
- 503 Service Unavailable
メンテナンスなどで該当サービスが定められた時刻まで使えないことがわかっている場合 - 301 Moved Permanently
ブラウザにリダイレクト（別ページへの移動）を指示しますが移動までに一定時間を置きたい場合（「このページは引っ越しました」などのメッセージを見せたい場合など。
ただこの 3xx 系での利用においてはブラウザが無視することも多いのでスクリプトやmeta タグを利用する方法を併用する場合も多いです）
特に計画メンテナンスの場合、メンテナンス終了時刻を Retry-After ヘッダーで指定することで検索エンジンのクローラーがヘッダーを解釈し、クロール間隔を調整してくれます。
これによりメンテナンス中にクローラーがアクセスしたときエラーのあるページとして検索エンジンのインデックスから除外されてしまうようなSEO への悪影響を抑える効果も期待できます。
上記した例は一般的なものですが、Web API で使用される場合は独自の意味合いを持つ可能性もあるため必ず仕様をご確認ください。
実装上の注意点
「Retry-After」は非常に便利なヘッダーですが、あくまでサーバーからの「 お願い 」です。
クライアントがこの指示に律儀に従うとは限らず、実装によっては無視されたり、指示より短い間隔でリトライされたりする可能性もあります。
サービスを提供する側でアクセス量の抑制のためにこのヘッダーを利用する場合は、サーバー側での防御（例えば、IP アドレスや API キーに基づいたレートリミット（単位時間あたりのリクエスト数制限）の実装なども検討が必要です。
仕事においても、「今、手が離せないので、30 分後に改めて声をかけます」と具体的な時間を提示されるのと、「今、忙しいです」とだけ言われるのとでは、その後の動きやすさがまったく違いますよね。
サーバー・クライアントの連携も同様で「○○という時間まで待ってから、もう一度アクセスしてください」とクライアントにリトライを促す「Retry-After」ヘッダーを用いて具体的な時間を示すことでサーバーにも、クライアントにも、利用者にも優しい設計につながります。
この記事が、皆さんの設計の一助となれば幸いです。
