QEHSQEHS
Book a demo

Developer portal

Idempotency-Key

Retry safety for mutating API requests. Network hiccups, timeouts, and worker restarts should never produce duplicate records.

Why you want it

If a POST / PUT / PATCH / DELETE succeeds on our side but the response never reaches your client, a naive retry creates a second record. Sending the same Idempotency-Key on the retry returns the original response verbatim, no duplicate.

How to use

  1. Generate a unique key per logical operation (UUID or ULID).
  2. Send it on the first request in the Idempotency-Key HTTP header.
  3. If the request fails mid-flight, retry with the same key and the same body.
  4. Once you treat the operation as complete, generate a new key for the next operation.
POST /api/v1/records
Idempotency-Key: 01HN9K4QZ8V5JY0M2NR0RPXZ3A
Content-Type: application/json

{"moduleKey":"incidents","title":"Near miss","severity":"medium"}

Rules we enforce

  • Keys must be 8–255 printable-ASCII characters, no whitespace. UUIDs + ULIDs + random hex work.
  • Keys are scoped per tenant. Two tenants cannot collide even on identical UUIDs.
  • Stored responses live for 24 hours; afterwards, the key is free to reuse.
  • Same key + same body → the original response is returned, status and headers preserved.
  • Same key + different body → HTTP 409 with errorCode: idempotency_key_conflict. Generate a fresh key for the new operation.
  • Our SDKs generate keys automatically on safe-retryable operations. Hand-rolled clients should generate their own.

Endpoints that honour the key

Every mutating endpoint (POST, PUT, PATCH, DELETE) honours Idempotency-Key when supplied. Read endpoints are already idempotent by definition and ignore the header.

Error catalog: idempotency_key_conflict →