重複処理を防いで安全に再試行する
リクエストを送信した後に応答を受け取れなかった場合は、再送が必要になることがあります。再試行用の識別値を付けると、サーバーは処理済みのリクエストかどうかを確認できます。
同じ識別値と同じ内容で再送すると、クーポンの二重発行やスタンプの二重付与をせず、最初の処理結果を返します。
使い方
新しい処理ごとに固有の再試行用識別値を作り、Idempotency-Key ヘッダーに入れてください。応答を受け取れず、同じ処理を再試行するときだけ同じ値を使います。
Request
curl -X POST "https://api.vivoldi.com/api/coupon/v1/create" \
-H "Authorization: APIKEY {YOUR_API_KEY}" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-20260920-000412" \
-d '{
"nm": "$5 discount coupon",
"discTypeIdx": 458,
"disc": 5
}'
ヘッダーを送れない場合は、リクエスト本文の requestId フィールドに値を入れられます。両方を送る場合、値は一致している必要があります。
| フィールド | 説明 | タイプ |
|---|---|---|
Idempotency-Key |
HTTP ヘッダー。半角英数字と . _ : - を使った8~64文字です。新しい処理ごとに異なる値を使用してください。 |
string |
requestId |
リクエスト本文のフィールド。ヘッダーの代わりに使用でき、形式も同じです。 | string |
適用範囲
クーポンの作成・使用、スタンプの作成・付与・取消・特典使用に適用されます。v2 のクーポン・スタンプ更新 API も再試行用識別値に対応しています。
識別値は任意です。指定しない場合は従来どおり処理されます。記録は72時間保持され、その後は同じ値でも新しい処理として扱われる場合があります。
識別値は組織と処理の種類ごとに管理されます。同じ組織内で異なる処理に同じ値を使い回さないでください。
応答とエラーへの対応
成功済みのリクエストを同じ識別値と内容で再試行すると、最初の処理結果を返します。処理や Webhook は再実行されません。
競合時は HTTP 409 が返り、応答本文の code も 409 になります。原因は message で確認してください。HTTP 200 でも code が 0 か確認してください。
| 状況 | HTTP | code |
対応 |
|---|---|---|---|
| 同じ識別値・同じ内容で再試行 | 200 | 0 | 最初の結果が返ります。追加の対応は不要です。 |
| 同じ識別値を別の内容に使用 | 409 | 409 | 新しい処理には新しい識別値を使用してください。 |
| 同じ識別値の先行リクエストを処理中 | 409 | 409 | 少し待ってから同じ識別値で再試行してください。 |
| ヘッダーと requestId の値が異なる | 400 | 1213 | 値を一致させるか、どちらか一方だけを送ってください。 |
| 識別値の形式が正しくない | 400 | 1216 | 半角英数字と . _ : - を使った8~64文字に修正してください。 |
| 別のリクエストが同じ対象を先に変更 | 409 | 409 | 最新の状態を確認してから、リクエスト内容を見直してください。 |
安全に再試行するためのヒント
- 注文番号など、同じ処理の再試行でも使える値を選んでください。毎回新しい値にすると、先のリクエストと結び付けられません。
- 応答を受け取れなかった場合は、同じ識別値と同じ内容で再試行してください。内容を変えた場合は新しい識別値を使います。
- HTTP 409 は原因によって対応が異なります。処理中なら時間を置いて再試行し、識別値の再利用や同時変更ならリクエスト内容を確認してください。