リアルタイム追跡リクエストがタイムアウト?再試行、フォールバック、従うべきステータスルール
リアルタイム追跡リクエストがタイムアウトした場合、荷物の最新ステータスは「遅延」「紛失」「変更なし」ではなく「不明」として扱ってください。再試行は限られた時間予算内でのみ行い、その後は明確にラベル付けした最後に確認できた更新情報を表示するか、後でもう一度確認するようユーザーに促してください。プロセス全体を通じて、リクエストの結果、データの鮮度、荷物の実際のステータスを分離して扱ってください。
この区別は、顧客向けの追跡ページだけでなく、追跡データを使って通知やサポート業務を開始するシステムにとっても重要です。タイムアウトが示すのは、時間内に応答が届かなかったということだけです。配送業者に新しいイベントがあるか、上流サービスがリクエストを処理したか、荷物が移動したかは分かりません。
まず、何がタイムアウトしたのかを特定する
追跡リクエストは複数の段階で失敗する可能性があります。ブラウザがアプリケーションからの応答を待つのを停止する場合、アプリケーションが追跡APIからの応答を待つのを停止する場合、またはそのAPIが別のサービスに接続している間にタイムアウトする場合があります。ユーザーにはいずれの場合も同じ一般的なエラーが表示されることがありますが、適切な次の対応は異なります。
- クライアント側のタイムアウト:アプリが待機を停止しました。サーバー側のリクエストは完了している可能性があります。重複処理を引き起こす可能性のある別のリクエストを発行する前に、自身のリクエストログまたは結果ストアを確認してください。
- ネットワークまたは接続障害:システムは利用可能な応答を受信できませんでした。リモートサービスがリクエストを処理したかどうか分からない場合があります。
- HTTP 504:ゲートウェイまたはプロキシが上流サーバーから時間内に応答を受信できませんでした。これはリクエスト経路を示すものであり、荷物を示すものではありません。
- HTTP 408:サーバーが、待機するよう準備していた時間内に完全なリクエストメッセージを受信できませんでした。これは配送業者の追跡ステータスではありません。
- 古いイベントを伴うHTTP 200:リクエストは成功しましたが、返された追跡情報は依然として古い可能性があります。HTTPレスポンスが成功したことは、データが最新であることを保証しません。
これらの結果はリクエスト診断情報として記録してください。いずれも「輸送中」「例外」「配達済み」などの荷物ラベルに変換しないでください。これらのラベルは、トランスポート層ではなく、追跡イベントまたは文書化されたステータスフィールドから取得する必要があります。
無制限のループではなく、上限付きで再試行する
読み取り専用の追跡照会では、タイムアウト後の再試行が妥当な場合があります。ただし、再試行には上限を設ける必要があります。繰り返しのリクエストは、問題を抱えているサービスへの負荷を高め、ユーザーの待ち時間を延ばし、複数のアプリケーション層が独立して再試行することで重複処理を生み出す可能性があります。
- 合計期限を設定する。初回試行と再試行を含め、ユーザー向けの処理にかけられる時間を決めます。呼び出し元が待機できる時間を超えるような、各試行への新たな完全期限は設定しないでください。
- 処理を安全に繰り返せるか確認する。通常、照会は配送登録、設定変更、リソース作成のリクエストとは異なります。プロバイダーの契約または冪等性制御によって安全性が確保されていない限り、状態を変更するリクエストを自動的に再送しないでください。
- 一時的な障害は控えめに再試行する。小さく明示的な再試行予算を使用し、多数のクライアントから同時に即時再試行を送るのではなく、ジッターを伴う遅延を設定してください。
- 適用されるサーバー指示に従う。レスポンスに有効な
Retry-Afterヘッダーが含まれている場合、それより早い再試行をスケジュールしないでください。また、より厳しいアプリケーション固有またはプロバイダー固有の制限にも従ってください。 - 期限または予算を使い切ったら停止する。フォールバックレスポンスに切り替え、ワークフローで必要な場合は後で別途照合をスケジュールしてください。
実用的な設計では、残り時間が十分にある場合にユーザー向けの再試行を1回だけ許可し、それ以降の試行をバックグラウンド更新に移すことが考えられます。これはポリシーの一例であり、普遍的なAPIルールではありません。サービスレベルの目標、観測されたレイテンシ、プロバイダーのドキュメントに基づいて制限を選択してください。また、HTTPライブラリ、ゲートウェイ、ジョブワーカーによる再試行も数えてください。そうしないと、一見控えめなアプリケーションポリシーでも、多数の上流呼び出しが発生する可能性があります。
HTTP 429の場合、レスポンスは直ちに再試行する理由ではなく、レート制限のシグナルとして扱ってください。HTTP 503はリクエストを一時的に処理できないことを示す場合があり、サーバーがRetry-Afterを提供することもあります。504は一時的な障害である可能性がありますが、次の試行が成功する保証はありません。認証エラーには通常、認証情報または権限の確認が必要であり、不正なリクエストには入力の修正が必要です。「見つかりません」という結果を返す追跡識別子には、より慎重な対応が必要です。プロバイダーの文書化された動作や配送段階によっては、記録を見つけるにはまだ早いか、識別子が間違っている可能性があります。そのような結果を1回受けただけで、荷物が存在しないと断定しないでください。
把握している情報を維持するフォールバックを選択する
最も安全なフォールバックは通常、最後に検証された追跡結果に、そのイベント時刻と正直な鮮度ラベルを付けて表示することです。その結果を現在のリクエスト失敗とは別に扱ってください。ページには「利用可能な最新の更新:施設を出発。最終確認:[時刻]。新しい更新は一時的に利用できません。」などと表示できます。「最終確認」はシステムが実際に記録している場合にのみ含めてください。これは配送業者のイベント時刻の代わりにはなりません。
サポートできる範囲で最も具体的な時刻を使用してください。配送業者のイベント時刻は、イベントが発生したと報告された時刻を示します。システムがそのイベントを受信した時刻は、取り込み時刻を示します。ユーザーがページを開いた時刻は、そのどちらでもありません。ソースが信頼できるイベント時刻またはタイムゾーンを提供していない場合は、時刻を作らないでください。同様に、キャッシュされた結果に取得時刻の記録がない場合は、最近更新されたと主張せず、「最後に利用可能な更新」と呼んでください。
フォールバックは次の3つの境界に従う必要があります。
- キャッシュデータはキャッシュデータとして表示する。古いイベントを、タイムアウトしたリクエストの結果として表示しないでください。
- 経過時間から進捗を推測しない。荷物が数日間輸送中だったというだけで、「配達に出発」とはなりません。
- 重要な不確実性を隠さない。以前の結果がない場合は、作り上げたデフォルトステータスを表示するのではなく、追跡が一時的に利用できないと伝えてください。
その他のフォールバック経路には、以前に同期された追跡ストア、承認済みの配送業者照会、後で実行するバックグラウンド更新などがあります。これらは、荷物、権限、データソースの利用規約に適合する場合にのみ使用してください。別のソースではイベント名や報告の遅延が異なる可能性があるため、出所を保持し、競合する記録を統合する場合はルールなしに統合しないでください。顧客が結果に基づいて行動できる場合は、スピナーを無期限に表示するのではなく、再試行またはサポートへの問い合わせ方法を提供してください。
リクエストステータス、データの鮮度、荷物ステータスを分離する
ユーザーインターフェースで一緒に表示する場合でも、これらは3つの異なるフィールドです。リクエストステータスは、照会が成功したか、タイムアウトしたか、エラーを受け取ったかを示します。データの鮮度は、返された情報または保存された情報がいつ確認されたかを示します。荷物ステータスは、追跡ソースが荷物について報告している内容を示します。これらを分離することで、一時的なAPI障害によって有効な配達イベントが上書きされたり、古い輸送中イベントが現在の状態として扱われたりするのを防げます。
たとえば、現在の更新がタイムアウトした場合でも、システムは以前の照会で確認された「配達済み」イベントを保持できます。配達イベントは消えません。正しい統合状態は、最後に利用可能な荷物ステータスが配達済みであり、最新の更新が失敗したというものです。一方、最後のイベントが「輸送中」の場合、タイムアウトは荷物が現在も輸送中であることを確認するものではなく、新しい回答を取得できなかったことだけを確認します。
イベントが順不同で到着した場合は、定義済みのルールを適用してください。利用可能であれば、イベント識別子、タイムスタンプ、ソース、プロバイダーが文書化したステータスの意味を比較します。システムが更新を受信した順序が、荷物イベントの発生順序であると想定しないでください。遅れて到着した古いイベントが、新しく検証されたステータスを自動的に置き換えることも避けてください。ただし、訂正や例外が正当な場合もあるため、配達後のステータス変更を不可能とみなす一律のルールは避けてください。基礎となるイベントを保持し、履歴を黙って書き換えるのではなく、矛盾を調査してください。
プロバイダーがHTTP 202を返した場合は、そのエンドポイントの契約に従って解釈してください。リクエストが受理されたことだけでは、追跡照会が完了したことにはなりません。同様に、HTTP 200は、そのエンドポイントの意味においてHTTPリクエストが成功したことを示すだけであり、すべての追跡フィールドが存在することや最新であることを証明するものではありません。プロバイダー固有のレスポンスフィールドは、プロバイダーのドキュメントを確認した後にマッピングしてください。
顧客を不安にさせず、オペレーターには障害を可視化する
有用な運用記録には、リクエストID、エンドポイントまたは操作、試行回数、経過時間、タイムアウト層、受信した場合のHTTPステータス、レスポンスがライブ照会からのものかフォールバックからのものかを含めます。追跡データについては、ソースと関連するイベント時刻または取得時刻を記録してください。追跡番号や顧客情報は、組織のアクセスおよび保持ルールに従って扱ってください。診断上の有用性は、制限のないログに完全な識別子を公開する理由にはなりません。
単一のタイムアウトに頼るのではなく、パターンを監視してください。特定の配送業者経路でのタイムアウト率の上昇、429レスポンスの繰り返し、配送業者のイベント時刻と取得時刻の差の拡大は、それぞれ異なる問題を示す可能性があります。最初のケースではプロバイダーの調査、2つ目ではレート制御、3つ目では同期またはイベント配信の確認が必要になる場合があります。17TRACK Tracking APIなどのプロバイダーを通じて追跡機能を提供する場合は、これらの一般的なルールを実装する前に、そのプロバイダーのドキュメントでエンドポイント固有のレスポンスフィールド、リクエスト制限、エラー処理を確認してください。
顧客向けメッセージは、正確かつ控えめにしてください。「現在、追跡情報を更新できませんでした。利用可能な最新の更新情報はこちらです。」必要に応じて、後でもう一度確認する、または販売者や配送業者が提示した予定配送期間を過ぎている場合はサポートに連絡する、といった次のステップを示してください。システムが保証できない更新時刻を約束しないでください。
タイムアウトに安全な追跡フローのリリースチェックリスト
- 各タイムアウトを設定する層と、再試行を管理する層を確認する。
- 合計リクエスト期限と、別個の上限付き再試行予算を設定する。
- 自動再試行される操作が安全に繰り返せることを確認する。
- レート制限と有効な
Retry-After指示に従う。 - リクエスト結果を荷物ステータスおよびイベント履歴とは別に保存する。
- フォールバックデータにラベルを付け、利用可能な場合はソースとタイムスタンプを保持する。
- キャッシュなし、古いキャッシュ、429、503、504、遅延レスポンスのシナリオをテストする。
- タイムアウトによって誤った配達通知が発生したり、検証済みイベントが消去されたりしないことを確認する。
基本原則は単純です。安全かつ有用な場合にのみリクエストを再試行し、識別可能な情報にのみフォールバックし、HTTPタイムアウトから荷物ステータスを決して断定しないでください。
よくある質問
タイムアウトした追跡リクエストはすぐに再試行すべきですか?
自動的に再試行してはいけません。操作を安全に繰り返せること、全体の期限に次の試行の時間が残っていること、レート制限の指示で待機を求められていないことを確認してください。読み取り専用の照会では、ジッターを伴う短時間の上限付き再試行が適切な場合があります。即時の再試行を繰り返すことは、適切なデフォルトではありません。
HTTP 504は配送業者の追跡システムが停止していることを意味しますか?
いいえ。ゲートウェイまたはプロキシが上流から時間内に応答を受信できなかったことを意味します。問題はそのリクエスト経路のどこにでも存在する可能性があります。配送業者全体の可用性や荷物の状態を示すものではありません。
タイムアウト後に最後に確認されたステータスを表示できますか?
はい。ただし、成功したライブ更新ではなく、利用可能な最新情報としてラベル付けしてください。分かっている場合はイベント時刻と取得時刻を表示し、新しい更新を確認できなかったことを明確にしてください。
タイムアウトによって荷物を「輸送中」から「例外」に変更すべきですか?
いいえ。タイムアウトはリクエストの失敗であり、荷物イベントではありません。信頼できる追跡ソースが変更を裏付けるイベントまたはステータスを提供した場合にのみ、荷物ステータスを変更してください。
タイムアウトしたリクエストが追跡記録を作成または登録していた場合はどうすればよいですか?
失敗したと決めつけないでください。レスポンスが失われる前に、リモートシステムが処理を完了している可能性があります。再送信する前に、既存の結果を確認し、文書化された冪等性メカニズムまたはプロバイダーが承認した復旧手順を使用してください。
参考資料
- RFC 9110, HTTP Semantics — HTTPステータスの定義、
Retry-After、リクエスト再試行に関する考慮事項。 - RFC 6585, Additional HTTP Status Codes — HTTP 429の定義と
Retry-Afterとの併用。 - Amazon Builders’ Library, “Timeouts, retries, and backoff with jitter” — 再試行の増幅、バックオフ、ジッターに関するエンジニアリング指針。
- 17TRACK Tracking API documentation — 実装前にプロバイダー固有のAPI動作を確認するためのリファレンス。


