Idempotency Keys: Exactly-Once API Delivery

Network Conditions

Packet loss rate 15%

Client retry delay 900 ms

Request rate 1.0 / s

Server Behaviour

Live Readouts

Requests sent (incl. retries)

Side-effects executed

Duplicate side-effects avoided by cache

Event Log

How it works

An API is idempotent for a given request when performing it once has the same server-side effect as performing it many times. Real networks don't guarantee delivery, and a client cannot tell "my request never arrived" from "it arrived and only the reply got lost" — so a correct client must retry on timeout, which by itself gives only at-least-once delivery:

client sends request(key=K)
  → [network] → server executes op, applies side effect
  ← [network] ← ack           (ack packet can be lost independently)
if no ack before timeout: client resends request(key=K)

Each packet in the scene rolls an independent loss chance on both legs of the trip. A lost outbound request means the server never saw it — safe to retry. A lost ack is the dangerous case: the server already ran the operation, but the client thinks it failed and retries anyway.

The fix is a server-side idempotency-key cache: the client sends the same key K on every retry of one logical operation. The server keeps a short-TTL map key → result (the glowing ring around the server node). On arrival it checks the cache first:

if cache.has(K):
    return cache.get(K)        // duplicate — no side effect, cached result replayed
else:
    result = execute(op)        // side effect happens exactly once
    cache.set(K, result, ttl)
    return result

Idempotency keys ON — a retry that reaches the server after the original already succeeded is recognised and short-circuited (cyan flash on the ring); "side-effects executed" stops climbing with retries.
Idempotency keys OFF — every arriving packet re-executes the operation, so a lost ack causes real double-processing (a duplicate charge, a duplicate order, a duplicate email).
The cache slots carry a fixed TTL (fades out over ~10s) — this mirrors real systems like Stripe's or PayPal's idempotency-key stores, which expire keys after a bounded window rather than keeping them forever.

Turn the toggle off and raise the loss rate to watch "duplicate side-effects" appear even though the client behaves identically in both cases — the difference is entirely a server-side design choice.

Request in flight Ack returning Lost in transit Cache slot occupied

⚠ Couldn't load the 3D engineThree.js failed to load from the CDN. Check your connection and reload.