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.
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 | 200 | 0 | The original result is returned. No further action is needed. |
| Same identifier used with different content | 409 | 409 | Use a new identifier for the new operation. |
| Earlier request with the same identifier is still processing | 409 | 409 | Wait briefly, then retry with the same identifier. |
| Header and requestId values differ | 400 | 1213 | Make the values match or send only one. |
| Invalid identifier format | 400 | 1216 | Use 8–64 ASCII letters, digits or these symbols: . _ : - |
| Another request changed the same item first | 409 | 409 | 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.