Skip to main content

Documentation Index

Fetch the complete documentation index at: https://www.zinc.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

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.

​
How it works

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.

​
Behavior on retry

If you send a request with a key that has already been used, Zinc returns an already_exists error rather than replaying the original response: 
{
  "code": "already_exists",
  "message": "Order with idempotency key 'a3f1...' already exists",
  "details": {
    "resource": "Order",
    "identifier": "a3f1c2d4-..."
  }
}
On a retry, this is success, not failure — your original request got through. Look the order up by its id (or by metadata) and move on.

​
Example

curl https://api.zinc.com/orders \
  -H "Authorization: Bearer <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotency_key": "a3f1c2d4-7b8e-4a9f-9c1d-2e3f4a5b6c7d",
    "products": [
      { "url": "https://www.amazon.com/dp/B07JGBW826", "quantity": 1 }
    ],
    "shipping_address": { ... },
    "max_price": 2300
  }'
If the call succeeds, store the returned order id. If it errors out, see below.

​
When to retry

  • 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.

​
Anti-patterns

These are real patterns we’ve seen cause duplicate orders or hide real failures.

​
Retrying every error

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.

​
Changing the key per attempt

Every one of these defeats idempotency: 
key                          attempt 1
key-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.

​
Treating a duplicate-key response as failure

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.

​
Not persisting the key before sending the request

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.