Idempotency

How it works

Idempotency-Key: 8d1c5b1e-3e0a-4d3c-9b8a-2f1e0c7a6b55

The key is any string unique per request — a UUID is fine. It is reserved before the effect, so two concurrent retries cannot both run: the second answers in_flight with a Retry-After.

Once the first attempt finishes, a retry with the same key answers refused with reason duplicate and how the first attempt ended. The original result is not returned: only that it happened is kept.

Without the header a retry is a new request. The protection lasts 24 hours.

Reads take no key: reading changes nothing, so there is nothing that could run twice.

In the clients

The SDKs take the key as the second argument and never invent one silently; the CLI and the n8n node generate one per call and echo it in the output, so you can retry exactly the same thing if the process died before reading the reply.