Sign in
Guides

Idempotency

Use idempotency keys to safely retry failed requests without accidentally creating duplicate orders.

How it works

Network failures, timeouts, and unexpected errors can leave you uncertain whether a request succeeded. Without idempotency, a naive retry might create a duplicate order and charge your balance twice.

By including an idempotencyKey field in the body of every order creation request (UUID v4 recommended), Giftronaut guarantees that the same key can never create more than one order. The first request with a given key creates the order and returns 201 Created. Any subsequent request that reuses the same key — regardless of whether the body is identical — is rejected with 409 DUPLICATE_IDEMPOTENCY_KEY; the original order is not replayed in the response.

Shell
curl -X POST "https://api.giftronaut.com/api/v1/orders/branded-cards" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotencyKey": "550e8400-e29b-41d4-a716-446655440000",
    "productId": "10042",
    "sendTiming": { "type": "IMMEDIATE" },
    "emailSetting": { "senderName": "Giftronaut Rewards", "subject": "Your gift has arrived!" },
    "recipients": [
      { "email": "alice@giftronaut.com", "firstName": "Alice", "amount": 50 }
    ]
  }'

Key requirements

  • Must be a unique string per logical operation (UUID v4 is ideal)
  • Maximum length: 64 characters
  • No expiry window: keys are checked against all past orders for your organization; there is no deduplication window and keys never expire
  • Keys are scoped to your organization — different orgs can reuse the same key

Response behavior

ScenarioHTTP statusBody
First request with a new key201New order object
Any retry with the same key (identical or different body)409Error: DUPLICATE_IDEMPOTENCY_KEY
A 409 DUPLICATE_IDEMPOTENCY_KEY means an order with that key already exists — it does not mean your order failed. If a network failure left you unsure whether the first request succeeded, do not blindly change the key and retry. Instead, confirm the outcome by looking up the order with your key: GET /api/v1/orders?clientOrderId={key}. If a matching order is returned, the original request succeeded.

Best practices

  • Generate the key before the request — not inside a retry loop
  • Store the key alongside your order record so you can look the order up later via GET /api/v1/orders?clientOrderId={key}
  • Include idempotencyKey in the body of every order creation request (POST)
  • GET and DELETE requests are inherently safe to retry