Idempotency

Automations retry — on a socket timeout, a 502 from a proxy, a queue redelivery, a CI step re-run. Without help, a retried "create task" makes a second task, and the client has no way to tell "my request never arrived" from "my request arrived and the response didn't".

Using it

Attach a unique value to a POST:

curl -X POST https://acme.krrim.com/api/v1/projects/APOLLO/tasks/ \
  -H "Authorization: Bearer krm_live_..." \
  -H "Idempotency-Key: 0f0d6a4e-3f6b-4a5f-8f6f-3a2f1b9c4d77" \
  -H "Content-Type: application/json" \
  -d '{"title": "Investigate checkout timeout", "priority": "high"}'

The first request runs normally and its response is remembered. Any later request with the same key gets that same response back — same status, same body — without the work happening twice.

Use a value derived from the thing you are creating (an upstream event id, a row id) rather than a fresh UUID per attempt. A key that changes between retries is no key at all.

The rules

The body is part of the match. Reusing one key for two different payloads is a client bug — almost always a key generated once and then cached too widely — and replaying the first response would silently drop the second request's data. That returns 409 rather than pretending to succeed.

Keys are scoped to the token. Two workspaces, or two integrations in one workspace, cannot collide on Idempotency-Key: 1.

A request still in flight returns 409, not a duplicate. Two concurrent retries of the same key would otherwise both run. The claim and the check are a single atomic operation, so exactly one wins and the other is told to wait.

How long a key lives

A remembered response stays replayable for 24 hours. That covers every retry pattern in practice — exponential backoff, a nightly job re-run, a human re-triggering a pipeline the next morning — without holding response bodies indefinitely.

After that the key is forgotten and a request carrying it is treated as new.

Reading the outcome