ホームブログTracking APIのエラーハンドリング：無効な追跡番号、レート制限、リトライを管理する方法

Tracking APIのエラーハンドリング：無効な追跡番号、レート制限、リトライを管理する方法

17TRACK

無効な入力、一時的な障害、レート制限、配送ステータスの結果を分けて、追跡APIのエラーを処理します。無効な追跡番号は、変更せずに再試行するのではなく、拒否または修正してください。スロットリングが発生した場合はリクエスト量を調整し、一時的な障害には上限付きの指数バックオフとジッターを用いて再試行します。登録やその他の書き込みリクエストを繰り返す前に、最初の試行が成功したかどうかを確認してください。

Tracking API Error Handling How to Manage Invalid Tracking Numbers

追跡データを注文管理システム、倉庫プラットフォーム、または顧客向け追跡ページに接続する開発者にとって、目標は単に失敗したリクエストを減らすことではありません。重複登録、再試行の集中、誤解を招く配送メッセージ、不要なサポート問い合わせを発生させず、信頼性の高い配送状況の可視化を実現することです。

応答を選ぶ前に失敗を分類する

追跡連携では、ネットワークリクエストが完了したか、APIが操作を受け付けたか、要求した各追跡項目が成功したか、配送イベントが利用可能かという、複数の異なる結果を評価する必要があります。これら4つを単一の成功または失敗フラグとして扱うと、回避可能なエラーが発生します。

HTTPの成功レスポンスは、バッチ内のすべての項目が成功したことを必ずしも意味しません。逆に、イベントがない追跡照会が正常に処理された場合も、必ずしもAPIの失敗ではありません。レスポンス本文を確認し、各結果についてプロバイダーが文書化している意味を適用してください。

条件推奨される対応変更せずに再試行？
形式不正の番号または無効なリクエストフィールド入力を検証して修正するいいえ
認証情報の欠落または無効認証情報、権限、環境を確認する修正するまで不可
レート制限レスポンス影響を受けた処理を遅延させ、共有リクエストの負荷を下げる必要な待機後、安全であれば可
一時的なサービス障害上限付きバックオフを適用し、操作の安全性を確認する通常は再試行予算内で可
登録送信後のタイムアウト登録が存在するかどうかを照合する無条件には不可
受け付けられたが配送イベントがない照会文書化された追跡ライフサイクルに従う短時間の再試行ではなく定期更新を使用する

HTTPステータスコードは出発点であり、プロバイダー固有の完全な判断ツリーではありません。RFC 9110はHTTPのセマンティクスを定義し、RFC 6585は429 Too Many Requestsを定義しています。連携システムでは、文書化されたアプリケーションエラーコードと項目レベルの結果も解釈する必要があります。

無効な追跡番号：不正な入力とイベントの欠落を区別する

「無効な追跡番号」は、形式不正の識別子、サポートされていない配送業者と番号の組み合わせ、必須の配送業者フィールドの欠落、その他プロバイダー固有の検証失敗など、異なる問題を指す場合があります。追跡イベントが返されないだけで、その番号が無効だと判断しないでください。

識別子を壊さずに検証する

  • 追跡番号は文字列として保存する。数値として保存すると、先頭のゼロが削除されたり、長い識別子が変更されたりする可能性があります。
  • 元の入力を保持する。変換内容を監査できるよう、正規化した値は別に保持します。
  • 控えめに正規化する。適切な場合は前後の空白を削除しますが、文書化されたルールで許可されている場合に限り、内部文字を削除したり大文字・小文字を変更したりしてください。
  • 必須フィールドをローカルで確認する。空の番号、配送業者識別子の欠落、無効なリクエスト形式を送信前に検出します。
  • 汎用的な追跡番号正規表現を避ける。ある配送業者向けに設計されたルールが、別の配送業者の有効な識別子を拒否する可能性があります。
  • フィールドの内容を確認する。エンドポイントが明示的に対応していない限り、注文番号、倉庫参照番号、配送業者の追跡番号は互換性がありません。

APIが入力を明示的に拒否した場合は、自動再試行ループではなく修正処理へ振り分けます。すべての検証問題を「追跡失敗」とするのではなく、「配送業者識別子が必要」などの有用な理由を含めてください。

「イベントなし」を別の状態として扱う

有用な移動イベントが利用可能になる前に、配送物に追跡識別子が付与される場合があります。適切な対応は、APIの文書化されたステータスモデルと配送状況によって異なります。識別子が配送システムから取得されたものか、配送業者の選択が正しいか、レスポンスが入力拒否ではなくデータ待ちを示しているかを確認してください。

input_rejected、awaiting_events、temporarily_unavailableなど、異なる内部状態を使用します。これらは推奨されるアプリケーション状態であり、標準化されたAPI値ではありません。一時的なデータ不足が不正確な顧客向けメッセージになるのを防ぐのに役立ちます。

ワーカー単位ではなく連携全体でレート制限を管理する

RFC 6585では、HTTP 429をレート制限レスポンスとして定義し、Retry-Afterヘッダーを含めることを許可しています。この標準は、追跡APIにおける普遍的な許容量やカウント方法を定めていません。制限はアカウント、認証情報、エンドポイント、その他の範囲ごとに文書化されている場合があるため、プロバイダーの実際のルールを使用してください。

RFC 9110では、Retry-Afterに秒数を示す0以上の数値とHTTP日付の2つの形式を定めています。両方を解析してください。値が日付の場合は、残りの待機時間を慎重に計算し、時計の差を考慮します。値がない、または使用できない場合は、設定済みのフォールバックバックオフポリシーを適用してください。

他のワーカーが同じ許容量を使い続ける状況では、1つのワーカーが独立してスリープするだけでは不十分です。関連する認証情報またはアカウントの共有境界でレート制御を行います。中央スケジューラー、共有トークンバケット、または同等の分散制御によって、そのトラフィックを調整できます。

  1. 影響を受ける範囲を特定する。制限がどのエンドポイント、認証情報、またはアカウントに適用されるかを確認します。
  2. サーバーの待機指示に従う。有効なRetry-After値で許可される時刻より早く再試行をスケジュールしないでください。
  3. 影響を受けたキュー処理を遅延させる。制限が実際に独立している場合は、無関係なトラフィックをブロックしないでください。
  4. 同時実行数またはリクエスト頻度を下げる。リクエストパターンを変えずに一度待つだけでは、同じ問題が再発する可能性があります。
  5. 間隔を空けて再開する。待機終了時にバックログ全体を同時に解放しないでください。

対応している場合、バッチ処理によってリクエスト数を減らせますが、文書化されたバッチサイズとカウントのルールを守る必要があります。1つのバッチが許容量を1単位だけ消費すると考えないでください。同様に、利用可能な場合はWebhookを使って不要なポーリングを減らしつつ、連携に必要な照合処理は維持してください。

バックオフとジッターを用いた上限付き再試行を行う

リクエストを変更せずに障害が解消する可能性があり、操作を繰り返しても安全な場合は、再試行が適切です。一時的な接続障害や一部のサーバーエラーはこのカテゴリに該当します。形式不正のペイロード、無効な認証情報、恒久的な権限問題などは、通常、修正が必要です。

実用的なフォールバックは、完全ジッターを用いた上限付き指数バックオフです。

backoff_window = min(max_delay, base_delay * 2^retry_index)
jitter_delay = random(0, backoff_window)
next_delay = max(valid_retry_after_delay, jitter_delay)

ここで、最初の再試行ではretry_indexが0から始まり、Retry-Afterがない場合は追加の最小待機時間をもたらしません。これらは実装上の選択であり、必須のHTTPアルゴリズムではありません。ワークロードとプロバイダーの指針に基づき、基本遅延、上限、試行回数、合計期限を選択してください。

ジッターは、すべてのワーカーが同じスケジュールで再試行するのではなく、リクエストを時間に分散させます。遅延の上限は指数部分を制限しますが、サーバーが要求する有効な待機時間がそれより長い場合に上書きしてはいけません。その待機時間がジョブの期限を超える場合は、早く再試行するのではなく、ポリシーに従ってジョブを延期または終了します。

すべての再試行チェーンに終端を設定する

  • 試行回数の上限：追加リクエストの数に上限を設けます。
  • 経過時間の上限：有効な処理時間を超えた処理の再試行を停止します。
  • 明確な責任範囲：どのレイヤーが再試行を制御するかを決め、HTTPクライアントの再試行とキューの再試行が予期せず乗算されないようにします。
  • 永続的なスケジューリング：短命なプロセス内で長時間スリープするのではなく、遅延ジョブを保存します。
  • 復旧経路：理由と次のアクションを付けて、再試行を使い果たしたジョブを確認可能な失敗ジョブキューへ送ります。

障害が長期化している場合は、通常の呼び出しを一時停止し、制御された復旧プローブを許可するサーキットブレーカーを検討してください。これはアプリケーションのレジリエンスパターンであり、特定の追跡プロバイダーが必要としていることを示すものではありません。

再送信する前に曖昧な書き込みを解決する

タイムアウトは、アプリケーションが完全なレスポンスを受信しなかったことを示します。サーバーがリクエストを拒否した、または処理しなかったことを証明するものではありません。追跡番号の登録や追跡設定の変更では、この違いが重要になります。

RFC 9110はべき等メソッドについて説明し、繰り返しが安全である、または元の操作が適用されていないと判断できる根拠なしに、べき等でないリクエストを自動的に再試行しないよう注意しています。すべての追跡エンドポイントが読み取り専用の照会と同じように動作すると想定せず、文書化された操作のセマンティクスを評価してください。

  • 利用可能な場合は、プロバイダーが文書化した冪等性の仕組みを、その適用範囲と保持ルールに従って使用します。
  • 同じ論理操作の再試行には同じ冪等性キーを使用します。任意のカスタムヘッダーが受け付けられるとは限りません。
  • 対応している場合は、曖昧な書き込みを繰り返す前に既存の登録を確認します。
  • プロバイダーが文書化した配送物の識別情報に沿ったローカル一意性制約を使用します。
  • 操作結果を保存し、キューの再配信によって別の書き込みが自動的に発生しないようにします。

バッチ操作では、各項目の結果を保存します。一時的な失敗に分類された項目だけを再試行し、結果が不明な項目は照合してください。バッチ全体を再実行すると、成功済みの処理を繰り返し、リクエスト許容量を不必要に消費する可能性があります。

追跡プロバイダーにポリシーを適用する

17TRACK連携では、プロバイダー固有の契約を確認する出発点として、Tracking API pageとofficial API documentationを使用してください。一般的なHTTPガイドの前提をハードコードするのではなく、エラー分類器を設定可能にしておきます。

実装前に、対象エンドポイントのリクエストスキーマ、レスポンスエンベロープ、項目レベルのエラーの意味、レート制限の範囲、バッチ制約、重複送信のルールを確認してください。イベント配信を使用する場合は、確認応答、認証、再配信の要件も確認します。このガイドは、17TRACKの具体的なレート制限値、再試行スケジュール、冪等性機能を規定するものではありません。

確認した各ルールを、プロバイダーのレスポンスからアプリケーションのアクション（入力修正、設定修復、待機、照合、エスカレーション）へのマッピングとして記録します。認識されないエラーは診断コンテキストを保持し、無制限の再試行をデフォルトにせず、上限付きのフォールバック経路に従わせます。

復旧品質を監視し、失敗経路をテストする

操作、エンドポイント、HTTPステータス、アプリケーションエラーコード、試行番号、レイテンシ、次に予定されているアクション、提供されている場合はプロバイダーのリクエスト識別子をログに記録します。APIキー、不要な住所情報、制限のないレスポンス本文は記録しないでください。完全な値が不要な場合は、追跡識別子をマスクまたはハッシュ化します。

無効な入力の割合、スロットリング、キューの経過時間、再試行の使い果たし、最後に成功した同期を個別に追跡します。HTTPエラー率が低くても、配送情報が古いままの連携はあり得ます。顧客向けページでは、最後に確認された配送ステータスを保持し、更新の失敗と配送業者が報告した配送例外を区別してください。

リリース前に、形式不正の入力、イベントのない有効な識別子、Retry-Afterの両方の形式、ヘッダーの欠落、部分的なバッチ失敗、書き込み後のタイムアウト、キューの再配信をテストします。また、再試行予算を使い果たすほど長い障害もシミュレートしてください。処理が予測可能な形で停止または延期され、成功した項目が不必要に再実行されず、失敗した項目が復旧可能な状態に残る場合にのみ、テストは合格です。

FAQ

無効な追跡番号は自動的に再試行すべきですか？

APIが入力を無効として明示的に拒否した場合は、再試行すべきではありません。まず番号、配送業者の選択、または必須フィールドを修正してください。レスポンスが配送イベントがまだ利用できないことを意味する場合は、検証失敗として扱うのではなく、文書化された更新ワークフローを使用します。

HTTP 200はバッチリクエストが完全に成功したことを意味しますか？

必ずしもそうではありません。操作レベルと項目レベルの結果について、プロバイダーのレスポンススキーマを確認してください。成功した項目を保存し、失敗を分離することで、1つの項目を再試行する際に残りを不必要に繰り返さないようにします。

追跡連携では何回の再試行を許可すべきですか？

普遍的な回数はありません。プロバイダーの指針、操作の安全性、結果が有用であり続ける時間に基づき、試行回数の上限と経過時間の予算を設定してください。スケジュールされたバックグラウンド同期と、対話型の顧客リクエストでは、許容できる復旧期間が異なる場合があります。

タイムアウトが発生したら、配送物を直ちに失敗とマークすべきですか？

いいえ。リクエストのタイムアウトは連携の結果であり、配送イベントではありません。最後に確認された追跡状態を保持し、安全な復旧をスケジュールし、接続問題を配送失敗通知に変換しないでください。

再試行を使い果たした場合はどうすべきですか？

診断コンテキストを付けて、ジョブを永続的な失敗ジョブキューまたは確認キューへ移動します。復旧に必要なのが入力修正、認証情報の復旧、プロバイダーの支援、または後で制御された再実行のいずれかを特定してください。ジョブを黙って破棄したり、同じ無制限の再試行サイクルを再開したりしないでください。

Sources

Loading