Use Idempotency-Key for safe retries

Overview

• Retry-sensitive public mutation endpoints can use Idempotency-Key so a timeout/retry does not create the same business action twice.
• Examples marked in the current API registry include Order creation, manual loyalty adjustments, Gift Card/Voucher redemption, and several Inventory stock/ledger/waste mutations.
• Some Inventory mutations require a retained Idempotency-Key rather than merely supporting it.
• Idempotency records are Business + route + key scoped and are retained for 24 hours.
• Reusing the same key with the same request can replay the saved response.
• Reusing the same key with a different request body returns 409 Conflict.
• If the first request is still processing, MiniTill can return 409 with Retry-After (currently 2 seconds) rather than allowing concurrent duplicate execution.

When to use this

• Use a unique idempotency key for every logical mutation that might be retried because of network timeout, process crash, or uncertain response delivery.

Step-by-step

1. Generate a UUID for the logical business operation.
2. Send it in Idempotency-Key with the first request.
3. If the response is lost, retry the same operation with the same key and identical request body.
4. If you intentionally perform a new operation, generate a new key.
5. If 409 says processing, respect Retry-After and retry the same request later.

Common mistakes

• Do not generate a new idempotency key on every network retry of the same operation.
• Do not reuse one key for two different request bodies/actions.
• Do not assume GET requests need idempotency keys.

Troubleshooting

• A mismatch 409 means the key was previously associated with different request content; use a new key for the new operation.
• If an endpoint requires retained idempotency, follow its OpenAPI/Postman documentation rather than sending the mutation without a key.