FlowGround
Back to Business Mode

Idempotency Keys

When a client doesn't get a clear response — a timeout, a dropped connection — it often retries the same request. For anything that changes state (charging a card, sending an email), an idempotency key lets the server recognize 'I've already done this exact operation' and return the original result instead of doing it again.

A client can never fully tell the difference between 'my request never arrived' and 'my request arrived and succeeded, but the response got lost' — so it has to be safe to retry either way
An idempotency key is a unique value the client generates once per logical operation and sends with every retry of that same operation — the server uses it to recognize a repeat
The server must store the key and its result BEFORE the side effect completes (or as part of the same transaction), so that even a retry racing the original request can't slip through and duplicate the charge
Idempotency keys should be scoped to a specific operation and expire after a reasonable window — reusing one indefinitely, or across genuinely different requests, defeats the safety they're meant to provide

Hands-on demo

Simulate a network timeout mid-payment

The client never gets a response, so it automatically retries the exact same $60 charge. Does the customer get billed once or twice?

Try it yourself

Try it yourself — run a scenario below, then flip this and replay it to see what changes.

Network Timeout, Safe Retry

A dropped connection triggers a retry that doesn't double-charge the customer.

Want this flow explained in detail as it plays?

checkout.flowground.dev

Checkout

Amount$60.00
Idempotency keyabc-123
Client
App
The request is sent with a client-generated unique key attached.

Selected hop

Client submits a $60 charge with idempotency key abc-123

Client

Whatever is sending the request — a browser, script, or API caller.

App

The application's backend — enforces business rules and decides what every request is allowed to do.

What happens here

The request is sent with a client-generated unique key attached.