Idempotency

POST and PATCH operations on the v1 API accept an Idempotency-Key header. When provided, the first successful response is cached for 24 hours and replayed for any retry with the same key.

curl https://www.clientcasa.com/api/v1/clients \
  -X POST \
  -H "x-api-key: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  -d '{ "name": "Acme Inc." }'

How it works

1. First request with a new key → resource created, response cached
2. Retry with the same key + same body → original response replayed (no duplicate created)
3. Retry with the same key + different body → 409 conflict (key reuse with payload mismatch)
4. After 24 hours, keys are eligible for cleanup; reusing an expired key acts like a new request

Choosing keys

• Generate a UUID v4 client-side per logical operation
• Reuse the same key when retrying transient failures (network errors, 5xx, timeouts)
• Use a fresh key when the input genuinely changes (re-trying with corrected data)

Which methods support it