Retries and idempotency

A request can time out after Klozeo has saved it. Send an Idempotency-Key header and a retry of the same request returns the first result instead of writing again.

When to send a key

Send a key on a request you might send twice: after a timeout, a network error or a 5xx, or when your automation retries on failure.

Route	Key
POST /leads (Create Lead)	Optional
POST /leads/batch (Batch Create)	Optional
POST /leads/{id}/notes (Create Note)	Optional

Other routes ignore the header. PUT and DELETE are already safe to repeat. A retry of any other POST route runs again.

How to send it

Add the header to the request:

curl -X POST https://api.klozeo.com/api/v1/leads \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: import-2026-11-13-row-42" \
  -d '{"name": "Acme Corp", "email": "[email protected]", "source": "website"}'

The key is 1 to 200 printable ASCII characters. Send the header once. An empty or too long key, other characters, or a repeated header return 400 invalid_idempotency_key:

{
  "error": "invalid_idempotency_key",
  "message": "Idempotency-Key must be 1 to 200 printable ASCII characters",
  "code": "invalid_idempotency_key"
}

What a retry returns

Send the same lead request with the same key again and you get the first response: same status, same body, plus a header:

HTTP/1.1 201 Created
Idempotent-Replayed: true

Nothing is written again: no audit entry, no webhook, no score refresh, no company lookup. A lead replay returns the original result even if the lead changed since. A 201 replays as 201 with the same id.

For POST /leads/{id}/notes, Klozeo does not store the note text. A replay returns the note as it is now. If the note was deleted since, it returns 410 note_already_deleted with the message “Note already created then deleted; no new note was created”.

Klozeo stores only committed results. A 4xx, 429 or 5xx is not stored, so a retry runs again. A replay counts as a request toward your rate limit.

Same key, different request

A key stands for one request. Send it with a different request and Klozeo returns 409 idempotency_key_reused. Nothing is written and the stored result is not returned:

{
  "error": "idempotency_key_reused",
  "message": "This Idempotency-Key was already used with a different request; send a new key for a new request",
  "code": "idempotency_key_reused"
}

Send a new key for a new request.

A request still running

If you retry while the first request is still running, Klozeo waits for it, then replays its result.

Past the 20-second write budget, it returns 409 idempotency_key_in_progress with Retry-After: 1. The message is “A request with this Idempotency-Key is still running; retry after Retry-After seconds”. Wait that long and send the same request with the same key again.

How long keys are kept

Klozeo keeps a key for 30 days. A key belongs to its workspace and to the API key (or dashboard session) that sent it: the same key sent with another API key is a different key. After 30 days, the same key counts as new.

Batches

One key covers the whole POST /leads/batch request. A replay returns the same 207 or 201 body.

After a 207, a retry with the same key returns the same 207. To resend only the failed items, send them as a new request with a new key. If no item at all was written, nothing is stored, so a retry with the same key runs again.

Choosing a key in n8n

In the HTTP Request node, turn on Send Headers and add a header named Idempotency-Key with this value:

{{ $workflow.id }}-{{ $execution.id }}-{{ $runIndex }}-{{ $itemIndex }}

The value is different for each item and each time the node runs in that execution. It is the same on every attempt within one execution, including Retry On Fail. Retrying a whole execution from the Executions list gives it a new id, so its keys are new.

What a key does not do

Use source_id to say which record a lead comes from. Use Idempotency-Key to say which attempt a request is. A key makes a retry of the same request safe; it does not compare leads. Matching still decides whether a new request creates or merges.

• Matching (email, SIREN, source_id, phone plus a similar name) runs on every new request. → Deduplication
• Two requests with different keys can still create two leads.
• A lead replay returns the original result, not the current data.

Do not use a record id alone as the key. If you sync that record again with changed data, it is a different request with the same key, and you get 409 idempotency_key_reused.