Skip to content

Glossary

Product & Engineering

Idempotency

Idempotency is the property of an operation that has the same effect whether it runs once or many times, so a request can be safely retried after a timeout without, for example, charging a customer twice.

Updated · By the VIZIO AI team

What is idempotency?

An idempotent operation can be repeated without changing the result after the first run. "Set the order status to shipped" is idempotent: running it twice still leaves the status as shipped. "Add $10 to the balance" is not: running it twice adds $20.

This matters because networks fail. A client often cannot tell whether a request failed or only the response was lost. If the operation is idempotent, the client can simply retry.

In HTTP, RFC 9110 defines PUT, DELETE and the safe methods (GET, HEAD, OPTIONS and TRACE) as idempotent. POST is not, which is why payment and order APIs add idempotency keys.

How do idempotency keys work?

The client sends a unique key with a request; the server stores the first result for that key and returns it again on any retry. Stripe's API is a common reference:

  • The client sends an Idempotency-Key header. Stripe suggests V4 UUIDs, and keys can be up to 255 characters.

  • For API v1, Stripe saves the status code and body of the first request once the endpoint starts running, and returns that saved response on retries, including 500 errors.

  • If the same key arrives with different parameters, Stripe returns an error.

  • Keys can be pruned once they are at least 24 hours old; a reused key after that starts a new request.

  • All POST requests accept keys. GET and DELETE do not need them, because they are idempotent by definition.

Other patterns are unique constraints in the database, upserts instead of inserts, and storing processed event IDs when consuming webhooks or queue messages.

What does idempotency look like in practice?

Make every step that moves money or creates records safe to run twice. Picture an online store where the payment step sometimes times out after the customer clicks Pay.

  1. When checkout starts, the server creates a key for that cart, such as a UUID stored with the draft order.

  2. The payment request to the provider carries that key. After a timeout, the server retries with the same key.

  3. The orders table has a unique constraint on the payment ID, so a second "payment succeeded" event cannot create a second order.

  4. The webhook handler records each event ID it has processed and skips repeats.

Say the customer double-clicks and the network drops a response. The customer is charged once and gets one order email.

What are the common idempotency mistakes?

Most idempotency bugs come from keys that are created at the wrong moment or checked in the wrong place.

  • New key per retry: creating a fresh key on each attempt defeats the purpose.

  • One key for different actions: two different payments that share a key will be rejected or merged.

  • Race conditions: two identical requests arriving together can both pass a "have I seen this?" check, unless the check and the write are atomic, for example through a unique constraint.

  • Side effects first: an email sent before the duplicate check still goes out twice.

  • Sensitive keys: Stripe advises against using email addresses or other personal identifiers as keys.

  • Expiry: retries that arrive after a key is pruned run as new requests.

How is idempotency different from deduplication and exactly-once delivery?

Deduplication drops repeated messages; idempotency makes the operation itself safe to repeat. Retries mean the same message can arrive twice, so consumers should expect duplicates. Deduplication filters them, usually by ID, within some time window.

Exactly-once delivery across a network is hard to guarantee. Systems usually get the same practical result by combining retries with idempotent handlers.

The idea also applies to data. A re-run ETL job should overwrite a day's data, not append it twice. In an agentic workflow, an AI agent may retry a tool call, so tools that write data need the same protection. It is a basic requirement of reliable API integration.

Idempotent vs non-idempotent operations

Idempotent

Non-idempotent

Example

Set status to shipped

Add $10 to a balance

HTTP methods

GET, HEAD, OPTIONS, TRACE, PUT, DELETE

POST, unless protected by a key

Safe to retry

Yes

Only with a key or deduplication

Typical safeguard

Correct design is enough

Idempotency keys, unique constraints

Risk if repeated

None

Duplicate records or double charges

How does Vizio AI approach idempotency?

Vizio AI's published case studies do not describe idempotency work in detail. It is a design rule that applies to any integration, payment flow or data pipeline.

Where to start: list every endpoint and scheduled job that creates records or moves money, and check what happens if each one runs twice.

logo of Facebook
logo of X
logo of LinkedIn
logo of Reddit
logo of Telegram

Think AI-first.
Move future-fast.

Let’s build what’s next! From product ideas and intelligent workflows to data-driven systems and scalable growth operations.

Book a Strategy Call