Glossary · Reliability
Idempotency key
Also called: Idempotency-Key header, dedupe key, request id
An idempotency key is a unique value a client sends with a request so that, if the same request is retried, the server recognizes it and returns the original result instead of doing the work a second time.
An operation is idempotent when doing it twice has the same effect as doing it once. Reading a record is naturally idempotent; "create an invoice" or "charge the card" is not. Networks fail in the worst possible place: the server did the work, but the response got lost, so the client can't tell whether to retry.
An idempotency key solves that. The client generates a key for the intent (not the attempt) and sends it on every retry:
POST /v1/runs
Idempotency-Key: order-10482-confirmationThe server stores the key with the result for a window (often 24 hours). A repeat with the same key gets the stored result back, and nothing runs again.
Choosing a good key
Derive it from the business event: order-{id}-confirmation, invoice-{vendor}-{number}. A random UUID generated per attempt defeats the purpose, because each retry looks new. A key that's too broad (customer-{id}) blocks legitimate second requests.
Inside automations
The same idea prevents the classic automation bug: a trigger fires twice and the CRM gets two contacts, or the customer gets two emails. Record the event's id when you handle it, and check it first next time. Pair it with exponential backoff so retries don't hammer a struggling API.
In Fluxo Flow
The REST API accepts an Idempotency-Key when starting a run: a retried request returns the same run instead of starting a second one. Webhook triggers honour Idempotency-Key (or x-fluxo-event-id) for 24 hours per workflow. Inside a workflow, a persistent Memory node can store handled ids so a Router skips anything already processed, and the Publish Output step has an Idempotency Key field you can template, such as order-{{input.order_id}}, for the systems you send to.
Read next
Related terms
- Exponential backoffExponential backoff is a retry strategy in which the wait before each new attempt grows exponentially (for example 1, 2, 4, 8 seconds), usually with random jitter, up to a maximum number of attempts or delay.
- Dead-letter queueA dead-letter queue is a holding place for messages or items that couldn't be processed after all retries, kept aside with their error so a person can inspect, fix and replay them instead of losing them.
- WebhookA webhook is an HTTP request that one system sends to a URL you give it, automatically, the moment an event happens, so the receiver doesn't have to keep asking.
- Rate limitA rate limit is a cap an API puts on how many requests a client may make in a time window; requests over the limit are refused, usually with HTTP status 429 Too Many Requests.
- iPaaSiPaaS, or integration platform as a service, is cloud-hosted software that connects applications and data sources and automates processes between them, without the buyer running integration servers.
- Human in the loop (HITL)Human in the loop (HITL) is a design in which an automated process pauses at chosen points for a person to review, correct, approve or reject its output before it continues.