idempotency

Repeating an operation has the same intended effect as doing it once.

Use this when A retried request or duplicate message repeats a side effect.

without the term

“Sometimes the payment webhook arrives twice, or the user double-clicks pay, and we charge or ship twice. Can you make it so doing the same thing twice only counts once?”

with the term · How do you ask a model for idempotency?

Make this handler idempotent. Use a stable operation key and test duplicate, concurrent, and crash-retried deliveries.

X Bluesky LinkedIn

What is idempotency?

An idempotent operation tolerates repetition. At-least-once message delivery makes duplicate handling part of normal operation.

Why does idempotency matter when vibe coding?

A successful happy-path test does not cover retries arriving concurrently or after a crash.

How do you do idempotency?

Choose a stable operation key and durable duplicate handling. Coordinate the recorded result with the side effect; use provider support for external effects.

What goes wrong with idempotency?

Recording completion separately from the side effect leaves a crash window.

Try a small example

Setting a saved preference is different from toggling it. Repeating the same assignment leaves the intended state unchanged.

let emailEnabled = true;
const disableEmail = () => { emailEnabled = false; };
disableEmail();
disableEmail();
console.assert(emailEnabled === false);

Compare this with flipping the boolean twice: that returns to the original state. For a network operation, also test concurrent retries and a crash between the side effect and recording the result. An in-memory example does not provide durable duplicate handling.

HTTP Semantics: idempotent methods

Before and after

A user wants notification emails disabled. The same request may be submitted twice. Compare a toggle with an explicit assignment to see why the operation's meaning matters before choosing a retry strategy.

Before

Toggling a preference expresses a change relative to the current state. Starting from true, one call turns emails off and the second call turns them back on.

function before(state) {
  state.emailEnabled = !state.emailEnabled;
}

After

Assigning false expresses the desired state directly. Starting from true, both one call and two calls leave emails disabled. The same operation has the same intended effect when repeated.

function after(state) {
  state.emailEnabled = false;
}

Check the change

Two toggle calls finish with emailEnabled equal to true; two disable calls finish with it equal to false. This is a deterministic state comparison. It makes no claim about request latency, payment safety, or production duplicate rates.

Save the runnable comparison, then run node --test idempotency.mjs with Node.js 22.12 or later.

Download the complete teaching example: the bug, prompt, runnable code, expected result, limits, and sources, linked back to this page.

Show the assertions

test('repeating the toggle reverses the requested change', () => {
  const state = { emailEnabled: true };
  before(state);
  assert.equal(state.emailEnabled, false);
  before(state);
  assert.equal(state.emailEnabled, true);
});

test('repeating the assignment preserves the desired state', () => {
  const state = { emailEnabled: true };
  after(state);
  assert.equal(state.emailEnabled, false);
  after(state);
  assert.equal(state.emailEnabled, false);
});

When this is not enough

A payment cannot usually become idempotent through assignment alone. A handler may need a stable operation key, durable storage, and coordination between the side effect and its recorded result. Test simultaneous duplicates, restarts, payload mismatches, and failures at that boundary. A database transaction cannot undo a completed external API call. Use the external provider's documented duplicate-handling mechanism where available. Idempotency does not require identical response bodies or forbid logging each request.

The next decision

unique constraint: Use a database-enforced key when competing writers must not create the same logical record twice.
transaction: Keep related database writes together; treat external side effects as a separate coordination problem.

Sources and verification

RFC 9110, section 9.2.2: Idempotent Methods
Idempotency concerns the intended effect of repeated requests, rather than identical responses.
Stripe: Idempotent requests
A concrete provider-specific operation key and replay contract; not a universal implementation recipe.

Sources checked 2026-10-09. These are illustrative examples with automated checks. How we check content.

Did this help with your task?

After trying the prompt or check, tell us what happened. This optional response records only your choice and this term.