Klantly Developers

Idempotency and concurrent updates

Prevent duplicate records on a retry and never accidentally overwrite a newer version.

Idempotency-Key

A network error or timeout does not mean your request failed. So with a POST, send an Idempotency-Key header with a unique value, for example a UUID:

cURL
curl -X POST "https://app.klantly.com/api/v1/customers" \
  -H "Authorization: Bearer $KLANTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f" \
  -d '{"email": "jan@example.com"}'
  • If you send the same request again with the same key, you get the same response back, with the header Idempotent-Replayed: true. Nothing is created twice.
  • The same key with a different body returns 422 idempotency_key_reused.
  • If the first request is still running, you get 409 idempotency_in_progress.

An Idempotency-Key is valid for 24 hours, per API key.

ETag and If-Match

Every single object comes with an ETag header. Send it in If-Match when you make a PATCH:

HTTP
PATCH /api/v1/customers/9d3f6c1e-4b2a-4c8e-9f1a-2b3c4d5e6f70 HTTP/1.1
Authorization: Bearer kly_4fZ2mQ8v...
If-Match: "3f2c9a41d6e8b07c5a2f"
Content-Type: application/json

If someone else changed the record in the meantime, you get 412 precondition_failed and nothing changes. Fetch the record again and retry. Without If-Match, the change is simply applied.

Last updated on September 14, 2026