Idempotency

Make order placement safe to retry.

Placing an order is a money movement, so it must be safe to retry. Send an Idempotency-Key header on POST /v1/orders and a retry with the same key never charges you twice.

curl https://api.sodacards.com/v1/orders \
  -H "X-API-Key: sc_live_your_key_here" \
  -H "Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  -H "Content-Type: application/json" \
  -d '{"product_id": "prod_123", "quantity": 1}'

Use a fresh unique key (a UUID) per distinct order, and reuse the same key when retrying that same order after a network error or timeout.

How it behaves

• Same key, same body → you get the original order back, charged exactly once.
• Same key, different body → 422 idempotency_key_reused. The key is bound to its first request; do not reuse a key for a different order.
• Same key, still processing → 409 request_in_progress. The first request has not finished; retry after a short delay.
• No key on a mutating request → 400 idempotency_key_missing.

Store the idempotency key with your order record before you send the request, so a crash mid-request still lets you retry with the same key.