Idempotency

Every state-changing endpoint accepts an Idempotency-Key header. We store the response for 24 hours, keyed on (app, endpoint, key). Retries with the same key return the same response — even if the original request succeeded after a network blip on your side.

When to use it

Set it on every POST, PATCH, PUT, and DELETE from a server. Generate a UUID per logical operation, not per HTTP attempt.

POST /v1/alarms/A-10293/acknowledge HTTP/1.1
Authorization: Bearer chekt_live_...
Idempotency-Key: ack-A-10293-2026-05-26T10:21:34

The contract

• Same key, same payload → same response (cached).
• Same key, different payload → 409 idempotency_conflict.
• Different key, same payload → executed twice. (Your call.)

What's not idempotent

GET requests are read-only by definition — no key needed. Streaming endpoints (/v1/events/stream) don't accept idempotency keys.

Best practice

Generate the key from a business identifier, not a random UUID. A key like dispatch-A-10293 survives a process crash; a fresh UUID per attempt doesn't.