LidmeoDevelopers

Idempotency

Replaying a write without any risk of doing it twice, with the Idempotency-Key header.

A connection drops, a response gets lost: your program doesn't know whether the write took place. With an Idempotency-Key, it sends it again safely: Lidmeo doesn't do it again, it returns the same response.

curl https://api.lidmeo.com/v1/prospects/pros_…/approve_invitation \
  -X POST \
  -H "Authorization: Bearer $LIDMEO_API_KEY" \
  -H "Idempotency-Key: approve-pros_1Hq3ZtV9kWmA-2026-10-01"
  • On every write: POST, PUT, PATCH, DELETE. A read doesn't need it.
  • The key: 1 to 255 characters, letters, digits and . _ : -. A random id (UUID) per operation works very well.
  • 24 hours: a key is kept 24 hours, for the API key or the connection that sent it, and for that account.

What happens

SituationResponse
New keyThe action takes place.
Same key, same request, action finishedThe original response, replayed, with the Idempotent-Replayed: true and Original-Request headers (the id of the original request, which the body keeps in request_id); Request-Id is the id of the replaying request. Nothing is done again.
Same key, action still in progress409 idempotency_key_in_use: retry in a moment.
Same key, another request (other body, other path)422 idempotency_key_mismatch: a key serves a single operation.
Same key, original response unreadable409 conflict: nothing is done again; start over with a new key.

A response that says what happened is kept, refusals included. A send that reached LinkedIn and then failed (502 send_failed) is kept too: the same key replays that refusal, it never sends again. Not kept: the other 5xx (most often a failure before any action) and transient refusals (409 import_in_progress, 409 send_in_progress…): the same key can then be retried, and the action is done again. After a 5xx on a write, read the object again before retrying: a write in several steps may have been partly applied (applied says so).

Stored responses are encrypted.

The SDKs do it for you

Every SDK write carries a key, the same on every new attempt: a write retried after a cut is never done twice. Give your own to tie it to your own operation:

await lidmeo.prospects.approveInvitation("pros_…", { idempotencyKey: "order-4521" });

Sends also have their own guards

Even without a key, Lidmeo never sends the same invitation or the same first message twice: the second request answers that it is already done, or that the prospect's state no longer allows it. The key additionally gives you the same response, word for word.

On this page