メインコンテンツへスキップ
このページは英語から翻訳されています。英語版が正式な情報源です。翻訳内容に不一致がある場合は、英語版を参照してください。

​
冪等性とリトライ

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

​
冪等性の仕組み

POST /labels エンドポイントは idempotencyKey フィールドを使用して、ラベル作成を安全にリトライできるようにします。指定したキーでの最初のリクエストがラベル作成を試みます。同じキーと同じ本文の後続リクエストは HTTP 200 で保存結果を返します。異なる本文でキーを再利用すると IDEMPOTENCY_CONFLICT の HTTP 409 が返ります。 最初のリクエスト — APIがラベルを作成し、HTTP 201を返します：
201 Created
リプレイされたリクエスト — 同じ idempotencyKey と本文は、新しいラベルを作成せず HTTP 200 で元の結果を返します：
200 OK（冪等リプレイ）
冪等性キーはAPIアカウントにスコープされています。異なるアカウントが同じキーを使用しても衝突しません。キーに有効期限はありません。 リトライ時は本文を変更しないでください。IDEMPOTENCY_CONFLICT の場合は元の本文で保存結果を取得するか、変更したリクエストに新しいキーを使用します。同じキーのまま customerOrderNumber だけを変更しても競合になります。 古いラベルや別のワークフローで作成されたラベルには、保存されたリクエスト指紋がない場合があります。その場合、キーを再利用すると本文が異なっていても従来どおり元の結果が返ります。競合検出に依存して古いラベルの内容を検証しないでください。
同じ idempotencyKey を持つ2件のリクエストを同時に送信しないでください。1件のリクエストを送信し、そのレスポンスを待ってから、必要な場合のみ同じキーでリトライしてください。同じキーを使った同時リクエストは重複排除されず、HTTP 500 で失敗することがあります。

​
冪等性キーの選択

キーは意図されたラベル作成を一意に識別する必要があります。良いパターン：
タイムアウトや一時的なサーバーエラーでは、元の idempotencyKey と変更していない本文を再利用してください。本文を変更する場合は新しいキーを使います。配送業者側で失敗したラベル（HTTP 502）の置換は「失敗したラベルのリトライ」を参照してください。
400バリデーションエラーの後、ラベルが作成されていないため同じ idempotencyKey を再利用できます。リクエストを修正して同じキーでリトライしてください。

​
リトライ戦略

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

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

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

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

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

同じ冪等性キーを再利用

元のリクエストと同じ idempotencyKey と変更していない本文でリトライしてください。成功後にレスポンスが失われた場合も保存結果を取得できます。
4

リトライ回数を制限

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

​
失敗したラベルのリトライ

失敗したラベルは、その idempotencyKey に対して最終的な結果であり、customerOrderNumber はそのまま保持されます。 まず原因を修正してください — 住所、プロダクトコード、アカウント設定など。配送業者による拒否のほとんどは一時的なものではありません。 その後、新しい idempotencyKey と 新しい customerOrderNumber（または省略して自動生成）で新しいリクエストを送信してください。番号を再利用すると 409 DUPLICATE_CUSTOMER_ORDER_NUMBER が返ります。推奨パターンは、試行番号の接尾辞を追加することです（例：N-2026-05-27-TEST-03-2）。ただし、完全な注文番号は40文字以内に収めてください。実際の注文参照は order.orderNumbers.referenceNumbers に保持してください。使用できる文字については顧客注文番号を参照してください。 失敗したラベルで返されるエラー本文については、配送業者の下流エラー 502 と 422をご覧ください。

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

​
障害シナリオ

ラベルが作成されたかどうか不明です。同じ idempotencyKey と変更していない本文でリトライしてください。試行が保存されていた場合、APIは保存されている失敗結果も含め、その結果をHTTP 200で返します。保存されていない場合は改めて作成を試み、成功すればHTTP 201を返します。
一時的なサーバーエラーです。同じ idempotencyKey でバックオフを使用してリトライしてください。
配送業者がリクエストを拒否しました。ラベルはこの idempotencyKey の下で status: failed として保存されます。同じキーでリトライしても、同じ失敗結果がHTTP 200で返され、配送業者には再度連絡しません。再度試すには「失敗したラベルのリトライ」をご覧ください。
リクエストが無効です。リクエストを修正せずにリトライしないでください。ラベルが作成されていないため、リクエストボディを修正した後に同じ idempotencyKey を再利用できます。
code を確認してください。IDEMPOTENCY_CONFLICT なら元の本文を使うか、変更したリクエストに新しいキーを使用します。DUPLICATE_CUSTOMER_ORDER_NUMBER なら既存ラベルを取得するか、別の注文番号を選択します。変更していない競合リクエストをそのままリトライし続けないでください。