API
Idempotency
Use the Idempotency-Key header to safely retry write operations.
Every POST and PATCH request on the v1 API accepts an Idempotency-Key
header. The key is claimed before the request runs, so a retry that arrives
while the first request is still in flight is refused rather than executed a
second time. The first successful response is then held for 24 hours and
replayed verbatim for any retry that sends 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." }'Rules
| Retry condition | Result |
|---|---|
| Same key + same body, first request still running | 409 request_in_progress with a Retry-After header. The write happens once. |
| Same key + same body, first request finished | Original response replayed. No new write. |
| Same key + different body | 409 idempotency_key_reused. |
| Same key, first request failed | Treated as a fresh request — the key is released on failure so a retry re-runs. |
| New key | Treated as a fresh request. |
| Key older than 24h | Treated as a fresh request; the expired row is reclaimed in place. |
Keys are organization-scoped — the same key value in two different orgs is unrelated.
Method support
| Method | Accepted | Notes |
|---|---|---|
POST | ✅ | All endpoints. |
PATCH | ✅ | All PATCH endpoints. Useful for status transitions that fire webhooks. |
GET | — | Read-only; safe to retry without a key. |
DELETE | — | Idempotent by definition; duplicate deletes are no-ops. |
Want patterns, not just the spec?
See the Idempotent writes tutorial for retry strategy, key persistence advice, and worked payment/refund examples.