Send idempotent Zinc API requests to safely retry orders without creating duplicates.
Every order Zinc places spends real money. An idempotency key is your guarantee that one logical purchase results in one charge — no matter how many times the request is sent.Use one on every order. It’s the only thing standing between a flaky network, a buggy retry, or an over-eager client and a duplicate order on a real card.
Include an idempotency_key in your request body. It can be any string up to 36 characters — a UUID is the right choice. Zinc enforces uniqueness on this key, so at most one order will ever exist for it, no matter how many times you send the same request.Use a fresh key for each new order. The same key always means the same order.
Retry on network problems and Zinc service errors. Timeouts, connection resets, and 5xx responses are usually transient. Use the same idempotency key and back off between attempts (e.g. 1s, 2s, 4s, capped at a few tries).
Don’t retry on errors caused by your request. Bad input, bad auth, insufficient funds — these will fail the same way next time. Fix the cause, then submit a new order with a new key.
An already_exists response on a retry means the original attempt succeeded. Treat it as success and stop retrying.
Don’t retry every error. Retrying validation, auth, or payment errors won’t make them go away. And if you “fix” the loop by changing the idempotency key on each attempt, you’ll create duplicate orders the moment Zinc recovers.
Treating every non-success response as retryable hides bugs in your integration. Auth, validation, and payment errors are deterministic — the next attempt will fail the same way.
key attempt 1key-retry attempt 2 (new key, new order)key_attempt_2 attempt 3 (new key, new order)newUuid() attempt 4 (new key, new order)`${key}-${Date.now()}` attempt N (new key, new order)
The whole point is that the key does not change between attempts of the same logical operation. If you append a counter, a timestamp, an attempt number, or generate a fresh UUID per retry, you’re creating N orders on N retries. Send the same string every time.
An already_exists response on a retry means the original request succeeded. Surfacing it as an error — or retrying with a new key — turns a successful order into a duplicate.
Generate the key, write it to your database alongside the pending order, then call Zinc. A key that lives only in memory is a key you can’t retry with if your process crashes mid-call.
Assistant
Responses are generated using AI and may contain mistakes.
