Idempotency

Why it matters

Network timeouts and client retries can otherwise create duplicate orders or tickets. With the same key and the same request body, the API returns the stored successful response instead of running the operation again.

Behavior

1. Send a unique Idempotency-Key per logical operation (UUID recommended).
2. The API hashes the request body and stores successful 2xx responses for that organization, method, path, and key.
3. Replay with the same key and same body → original status and body, plus header Idempotency-Replayed: true.
4. Reuse the same key with a different body → 409 idempotency conflict.

Failed non-success responses are not stored for replay; you may retry with the same key after fixing transient errors, as long as the body stays identical.

Example

curl -X POST https://api.cowtic.com/api/v1/orders \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{
    "eventId": "evt_…",
    "customer": { "email": "guest@example.com", "name": "Ada Guest" },
    "items": [{ "ticketId": "tt_…", "quantity": 2 }]
  }'

Client guidance

• Generate the key before the first attempt and reuse it on retries.
• Do not rotate the key when only retrying the same payload.
• Use a new key for a new logical purchase or issue request.