Retry safely without duplicate processing

If you sent a request but did not receive a response, you may need to send it again. Include a retry identifier so the server can tell whether it has already processed the request.

Retrying with the same identifier and request content returns the original result without issuing a coupon or adding a stamp twice.

How to use it

Create a unique retry identifier for each new operation and send it in the Idempotency-Key header. Reuse the identifier only when retrying that same operation after receiving no response.

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
  }'

If you cannot send the header, use the requestId field in the request body instead. If you send both, their values must match.

Fields Description Type
Idempotency-Key HTTP header. Use 8–64 characters: ASCII letters, digits, . _ : -. Use a different value for each new operation. string
requestId Request body field. It can replace the header and follows the same format. string

Where it applies

This applies to coupon creation and redemption, stamp creation, addition, removal and reward redemption. The v2 coupon and stamp update APIs also support retry identifiers.

The identifier is optional. Without it, requests follow the existing behavior. Records are kept for 72 hours; after that, a request with the same value may be treated as a new operation.

Identifiers are scoped by organization and operation type. Do not reuse a value for different operations within the same organization.

Responses and error handling

Retrying a successful request with the same identifier and content returns the original result. The operation and webhook are not run again.

Conflicts return HTTP 409 with code 409 in the response body. Check message for the cause. Even with HTTP 200, check that code is 0.

Situation HTTP code What to do
Retry with the same identifier and content 2000 The original result is returned. No further action is needed.
Same identifier used with different content 409409 Use a new identifier for the new operation.
Earlier request with the same identifier is still processing 409409 Wait briefly, then retry with the same identifier.
Header and requestId values differ 4001213 Make the values match or send only one.
Invalid identifier format 4001216 Use 8–64 ASCII letters, digits or these symbols: . _ : -
Another request changed the same item first 409409 Check the latest state, then review your request.

Safe retry practices

  • Choose a value such as an order number that you can reuse when retrying the same operation. A new value on every attempt cannot link back to the earlier request.
  • If you receive no response, retry with the same identifier and request content. If the content changes, use a new identifier.
  • Handle HTTP 409 according to its cause. If processing is still in progress, retry later. For identifier reuse or a concurrent change, review the request.