【ITニュース解説】Honoring Retry-After and Upstream Hints When NHTSA Slows Down

システムが外部のサービス（API）を利用する際、そのサービスが一時的に混み合ったり、応答が遅くなったりすることがよくある。この記事は、そのような状況でどのようにシステムを賢く振る舞わせるかについて解説している。特に、アメリカの高速道路交通安全局（NHTSA）が提供する車両識別番号（VIN）のデコードサービスを例に挙げながら、APIを適切に利用するための技術的な工夫を説明する。

システムがAPIにリクエストを送り、サーバーが処理しきれない状態になると、通常はエラー応答を返す。例えば、「429 Too Many Requests」や「503 Service Unavailable」といったHTTPステータスコードがこれにあたる。このようなエラーを受け取った際、システムはすぐにリクエストを再試行しようとするのではなく、一時停止してからもう一度試す「リトライ」という処理を行うことが一般的だ。

しかし、単純なリトライは問題を悪化させる可能性がある。多くのシステムが一斉にリトライを始めると、サーバーへの負荷はさらに増大し、結果として誰もサービスを利用できなくなる「ハードブロック」状態に陥ることもある。これを防ぐために「ジッター付き指数バックオフ」という手法が広く使われている。これは、エラーが発生するたびにリトライまでの待ち時間を指数関数的に長くしていき、さらにランダムな時間（ジッター）を加えることで、多くのクライアントが同時にリトライすることを避け、サーバーへの負荷を分散させる方法だ。

しかし、記事ではジッター付き指数バックオフだけでは不十分だと指摘している。なぜなら、サーバー自体が「これだけ待ってから再試行してほしい」という明確な指示を出している場合があるからだ。この指示は、HTTPレスポンスヘッダに含まれる「Retry-After」という情報で伝えられる。

「Retry-After」ヘッダには、主に二つの形式がある。一つは「Retry-After: 120」のように、何秒後に再試行すべきかを示す秒数で、もう一つは「Retry-After: Wed, 07 Oct 2026 12:00:00 GMT」のように、特定の日時を示すHTTP日付形式だ。これらの情報は、サーバーが現在の負荷状況を判断して計算した、最も適切な待機時間を示すものだ。また、APIとクライアントの間に立つプロキシサーバーや、エラー応答のJSONボディ内にretryAfterMsといった形で待機時間が示されることもある。これらも「Retry-After」ヘッダと同様に、サーバーからの重要なヒントとして扱うべきだ。

これらのサーバーからのヒントを無視すると、いくつかの問題が発生する。まず、サーバーが指定した時間よりも早くリトライしてしまい、再度サーバーに余計な負荷をかけ、利用枠を無駄に消費することになる。次に、システムを過負荷から保護するための「サーキットブレーカー」のような機能が、実際にはクライアント自身が引き起こしたノイズ（頻繁なエラーと再試行）によって誤動作する可能性がある。さらに、ユーザーはAPIの応答が不安定になり、サービスが使えたり使えなかったりする不快な体験をすることになる。これは、クライアントがサーバーの指示に従わず、自己流のタイミングでリトライを試みているために起こる摩擦だ。

したがって、これらのヒントを適切に処理するシステムを構築することが重要となる。そのための具体的な実装手順は以下の通りだ。

まず、**パース（解析）**のステップだ。「Retry-After」ヘッダの値は文字列として届くため、これを秒数や日付の形式に変換し、ミリ秒単位の待機時間に計算し直す必要がある。例えば、「120」という文字列からは120秒、つまり120,000ミリ秒という待機時間を導き出す。日付形式の場合は、現在時刻との差分を計算して待機時間を求める。

次に、**クランプ（制限）**を行う。サーバーから受け取った待機時間をそのまま採用するのではなく、最小値と最大値の範囲内に収める処理だ。例えば、待機時間が短すぎる（例: 0ミリ秒）とすぐにリトライしてしまい、長すぎる（例: 1時間以上）とユーザーを不必要に待たせてしまう可能性がある。記事の例では、最小250ミリ秒、最大60,000ミリ秒（1分）という範囲を設定している。これは、極端な値や不正な値を受け取った場合に、システムが安全かつユーザー体験を損なわない範囲で動作するためのガードレールとなる。

そして、最終的にその待機時間だけ**スリープ（一時停止）**する。これにより、システムはサーバーが指定した、あるいは計算された時間だけ処理を停止し、その後でリトライを行う。

待機時間を決定する際には、いくつかの優先順位がある。 最も優先されるのは、HTTPステータスコードが「429」（リクエスト過多）や「503」（サービス利用不可）の場合に、サーバーが明示的に返した「Retry-After」ヘッダの値だ。これはサーバーからの直接的な指示であるため、最優先で尊重すべき情報となる。 次に優先されるのは、プロキシやサーバーのJSONボディに含まれるretryAfterMsなどの待機時間ヒントだ。これもサーバー側の意図を汲んだ情報とみなされる。 これらの明示的なヒントがない場合や、HTTPタイムアウト、その他のサーバーエラー（「502 Bad Gateway」や「504 Gateway Timeout」など）が発生した場合には、ジッター付き指数バックオフのロジックを使って待機時間を計算する。このように、明確な指示があればそれに従い、なければバックオフ戦略で対応するという優先順位を設けることが、賢いAPI利用の鍵となる。

このリトライロジックは、API呼び出しを行う「フェッチ関数」のような中心的な場所に実装すべきだ。ユーザーインターフェース（UI）のコンポーネントが個別にリトライのロジックや待機時間を決めると、システム全体で統一性がなくなり、かえって混乱を招く。API呼び出しの関数内で、レスポンスのステータスコードやヘッダを解析し、適切な待機時間を計算して実行する一連の処理を完結させるべきだ。

また、ユーザー体験（UX）への配慮も非常に重要だ。例えば、サーバーが「45秒後に再試行せよ」と指示した場合、システムの裏側で45秒間待つのは技術的には正しい。しかし、もしUIに「処理中…」と表示されたまま45秒も経過すれば、ユーザーはシステムがフリーズしたと感じたり、不満を感じたりするだろう。そのため、自動で待機する時間には上限を設けるべきだ。記事では60秒という上限を例に挙げている。この上限を超えそうな場合は、システムは自動で待機するのをやめ、ユーザーに直接「サービスが混み合っています。1分ほど経ってからもう一度お試しください」といった正直なメッセージを表示すべきだ。これにより、ユーザーは現在の状況を理解し、適切な行動をとれるようになる。同時に、同じリクエスト（例えば、同じVINのデコード）に対して、システムが複数のリトライを並行して実行しないように、「シングルフライト」という仕組みを導入することも大切だ。

最後に、どのようなエラーでもリトライすべきではない、という点も重要だ。例えば、ユーザーが不正な入力データを提供したために発生する「400 Bad Request」のようなエラーに対して「Retry-After」ヘッダが返されても、それを信用してリトライすべきではない。入力データが間違っている限り、待っても解決しないからだ。また、API呼び出し自体は成功（200 OK）したものの、期待していたデータが一部欠けている場合なども、リトライの対象とはならない。リトライは、あくまで一時的なサーバー側の問題によって発生したエラーに対してのみ行うべき処理だ。

まとめると、NHTSAのような公共のAPIや、自分たちが構築するプロキシサーバーが「待て」という指示を出したとき、「Retry-After」ヘッダやJSONボディ内の待機時間ヒントは、APIを利用する上での重要な「契約」の一部と考えるべきだ。これらのヒントを正しく解析し、安全な範囲で待機時間を制限し、明示的なヒントがあれば自前のバックオフよりもそちらを優先する。そして、自動的な待機時間が長すぎると判断した場合には、ユーザーに正直に状況を伝える。このように、意図的に待機時間を守ってリトライすることで、私たちは公共のデータサービスを健全に利用する「良い市民」となり、安定したサービスをユーザーに提供できるのだ。