Fundamentals
Idempotency
Sending the same request twice must not create a second record — how Idempotency-Key works.
Networks are unreliable. You send a POST, no response comes back — you cannot tell whether it reached the server. Resend and you may create a second record; don't and you may have created none.
Idempotency-Key removes that uncertainty.
Usage
curl -X POST "https://acme.crm.blesyum.app/api/crm/public/v1/contacts" \
-H "Authorization: Bearer blsk_..." \
-H "Idempotency-Key: 9f2c1e40-6b3d-4a1f-9c2e-7d5b8a1f3c4e" \
-H "Content-Type: application/json" \
-d '{"email":"jane@example.com","name":"Jane Doe"}'Send it a second time with the same key: no new record, and the first request's response is replayed. Same status, same body.
You generate the key
The key is a unique value you produce (a UUID is a good choice). The correct pattern: generate it once when you build the request and use the same one for every retry.
const idemKey = crypto.randomUUID();
async function createContact(body: unknown) {
// EVERY retry carries the same key — otherwise idempotency means nothing.
return request(url, {
method: "POST",
headers: { "Idempotency-Key": idemKey, "Content-Type": "application/json" },
body: JSON.stringify(body),
});
}Generating a fresh key on each attempt is the same as turning idempotency off. It is the most common mistake here.
Same key, different body → 409
The server keeps a fingerprint of the request: method + path + a digest of the body. Reusing a key with a different body gives 409:
{ "error": { "code": "CORE-REQ-0005",
"message": "This idempotency key was used with a different request." } }That is a safeguard: accidentally reusing a key would otherwise make one of two distinct operations vanish silently.
Retention
Records are kept for 24 hours. Within that window the same key replays the stored response; after it the key is free again.
An interrupted request
If the process crashes while the first request is in flight, the record stays "locked". That lock is released automatically after 60 seconds and the request can run again — no permanent 409 wall.
Which endpoints
Any write endpoint with a side effect. It is meaningless on GET requests (those are already idempotent) and is ignored there.
Calling from a queue or worker? Derive the idempotency key from the job record's id (job:{id}). The key is then automatically identical on retry and you never have to store it separately.