Skip to main content
このページは英語から翻訳されています。英語版が正式な情報源です。翻訳内容に不一致がある場合は、英語版を参照してください。

​
冪等性とリトライ

配送ラベルには実際のコストと物流への影響があります。重複ラベルは運用上の混乱、配送コストの無駄、在庫追跡のエラーを引き起こします。Flex Forward APIには、これを防止する冪等性が組み込まれています。

​
冪等性の仕組み

POST /labels エンドポイントは idempotencyKey フィールドを使用して、各ラベル作成リクエストが一度だけ処理されることを保証します。 最初のリクエスト — APIがラベルを作成し、HTTP 201を返します：
201 Created
リプレイされたリクエスト — 同じ idempotencyKey は新しいラベルを作成せずに、HTTP 200で元の結果を返します：
200 OK（冪等リプレイ）
冪等性キーはAPIアカウントにスコープされています。異なるアカウントが同じキーを使用しても衝突しません。

​
冪等性キーの選択

キーは意図されたラベル作成を一意に識別する必要があります。良いパターン：
同じ論理リクエストをリトライする際に、新しい idempotencyKey を生成しないでください。APIが重複を検出できるよう、元のキーを再利用してください。
400バリデーションエラーの後、ラベルが作成されていないため同じ idempotencyKey を再利用できます。リクエストを修正して同じキーでリトライしてください。

​
リトライ戦略

一時的な障害（HTTP 500、502、またはネットワークタイムアウト）の場合は、指数バックオフでリトライしてください：
1

リクエストタイムアウトを設定

HTTPリクエストに適切なタイムアウト（例：30秒）を使用してください。
2

障害発生時、リトライまで待機

指数バックオフを使用：1秒、2秒、4秒、8秒。
3

同じ冪等性キーを再利用

常に元のリクエストと同じ idempotencyKey でリトライしてください。元のリクエストが成功したがレスポンスが失われた場合でも、重複ラベルが作成されないことが保証されます。
4

リトライ回数を制限

3〜5回のリトライで停止してください。それでも失敗する場合は、エラーを記録して調査にエスカレーションしてください。

​
エンドポイント別の冪等性

​
障害シナリオ

ラベルが作成されたかどうか不明です。同じ idempotencyKey でリトライしてください。ラベルが作成されていた場合、APIはHTTP 200で元の結果を返します。作成されていない場合、ラベルを作成してHTTP 201を返します。
一時的なサーバーエラーです。同じ idempotencyKey でバックオフを使用してリトライしてください。
配送業者サービスがエラーを返しました。ラベルは status: failed で保存されています。リトライする前にエラーメッセージを確認してください — 一部の配送業者エラーはリクエストの変更が必要です（無効な住所など）。一時的な配送業者の問題の場合は、同じ idempotencyKey でリトライしてください。
リクエストが無効です。リクエストを修正せずにリトライしないでください。ラベルが作成されていないため、リクエストボディを修正した後に同じ idempotencyKey を再利用できます。