メインコンテンツへスキップ

​
冪等性とリトライ

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

​
冪等性の仕組み

POST /labels エンドポイントは idempotencyKey フィールドを使用して、各ラベル作成リクエストが一度だけ処理されることを保証します。 最初のリクエスト — APIがラベルを作成し、HTTP 201を返します： 
curl -X POST https://api.flexforward.com/labels \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotencyKey": "ord-20250301-abc123",
    "courier": "yunexpress",
    ...
  }'
201 Created
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "created",
  "courier": "yunexpress",
  "courierOrderNumber": "YT2503010001",
  "courierTrackingNumber": "YT2503010001CN",
  "error": null
}
リプレイされたリクエスト — 同じ idempotencyKey は新しいラベルを作成せずに、HTTP 200で元の結果を返します：
200 OK（冪等リプレイ）
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "created",
  "courier": "yunexpress",
  "courierOrderNumber": "YT2503010001",
  "courierTrackingNumber": "YT2503010001CN",
  "error": null
}
冪等性キーはAPIアカウントにスコープされています。異なるアカウントが同じキーを使用しても衝突しません。

​
冪等性キーの選択

キーは意図されたラベル作成を一意に識別する必要があります。良いパターン：
パターン例ユースケース
注文IDord-20250301-abc123注文ごとに1ラベル
注文+連番ord-20250301-abc123-1注文ごとに複数ラベル
UUIDf47ac10b-58cc-4372-a567-0e02b2c3d479汎用
同じ論理リクエストをリトライする際に、新しい idempotencyKey を生成しないでください。APIが重複を検出できるよう、元のキーを再利用してください。
400バリデーションエラーの後、ラベルが作成されていないため同じ idempotencyKey を再利用できます。リクエストを修正して同じキーでリトライしてください。

​
リトライ戦略

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

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

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

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

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

同じ冪等性キーを再利用

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

リトライ回数を制限

3〜5回のリトライで停止してください。それでも失敗する場合は、エラーを記録して調査にエスカレーションしてください。
試行 1: POST /labels → タイムアウト
  1秒待機
試行 2: POST /labels → 502
  2秒待機
試行 3: POST /labels → 200（冪等リプレイ — ラベルは試行1で作成されていた）

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

エンドポイント冪等メカニズム
POST /labelsはいidempotencyKey フィールド — すべてのリクエストで必須
GET /labels/{id}はい読み取り専用 — 自然に冪等
GET /tracking/{id}はい読み取り専用 — 自然に冪等

​
障害シナリオ

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