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 X-Idempotency-Key header with a unique string (UUID v4 recommended), Giftronaut will return the original response if the same key is seen again within the deduplication window — without re-executing the operation.

curl -X POST "https://api.giftronaut.com/api/v1/orders/branded-card" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{ ... }'

Key requirements

Must be a unique string per logical operation (UUID v4 is ideal)
Maximum length: 128 characters
Deduplication window: 24 hours
Keys are scoped to your organization — different orgs can reuse the same key

Response behavior

Scenario	HTTP status	Body
First request succeeds	`201`	New order object
Retry within window (same key)	`200`	Original order object
Duplicate detected, key reused with different body	`409`	Error: `DUPLICATE_IDEMPOTENCY_KEY`

Best practices

Generate the key before the request — not inside a retry loop
Store the key alongside your order record so you can identify replayed responses
Only use idempotency keys on mutating requests (POST, PUT, PATCH)
GET and DELETE requests are inherently safe to retry