What should the server return for a legitimate duplicate?

The stored result of the original request, with the original status. The client cannot tell it was a duplicate, which is the point.

How long should keys be kept?

Longer than your clients retry. If a job retries for a week and keys expire in a day, the protection silently stops applying before the retries do.

Does an idempotency key make everything safe?

No. It makes one call safe to repeat. A workflow of several calls needs each step to be safe, which is a separate piece of work.

Idempotency Scenario Generator

An idempotency key looks simple until you write the tests. The same key with the same body is the easy case. The hard ones are the same key with a different body, two identical requests arriving at once so there is no stored result yet, a key that expired before the client finished retrying, and a multi-step workflow where the first attempt got halfway. Worst of all is the client that generates a fresh key on every attempt, which is a common implementation and provides no protection whatsoever.

How many scenarios

There are 6 distinct idempotency scenarios — it will not repeat them to pad a list.

Seed (optional)

A word brings the same set back, for a test plan you can re-derive.

Narrow it down

Only ones that are safe to retry

Only ones where the work already happened

Your idempotency scenarios will appear here.

What this generator does

Produces the situations an idempotency mechanism must survive, each with the behaviour that would be correct. The catalogue deliberately includes the two cases that make correct implementations look broken and broken ones look correct: returning a conflict instead of the original result, and generating a new key per attempt.

How to use this tool

Choose how many scenarios you want.
Filter to the cases where the work has already happened, which are the expensive ones.
Draw, then copy the set into your test plan.
Seed it if the plan needs to be reproducible.

Understanding the controls

How many scenarios: Six distinct idempotency scenarios. It will not repeat them to make the list longer.
Narrow it down: Two filters that change what you are practising. Safe-to-retry-only gives the cases a retry policy handles; work-already-happened gives the cases it does not, which are the ones that cost money.
Seed: Any word makes the draw reproducible, so a test plan can be re-derived from the same seed months later. Leave it empty for a different set each time.

Common use cases

Writing the test plan for a payment, booking or messaging endpoint
Reviewing whether an idempotency implementation actually protects anything
Checking that concurrent retries cannot both start the work
Deciding how long keys must be honoured, given how long clients retry
Explaining to a team why the outer key does not make a multi-step workflow safe

How this generator works

A hand-written catalogue, shuffled without replacement, with a coherence check before display so that a scenario cannot claim both that the work already happened and that it occurs before the request is sent.

Randomness and fairness

Which scenarios you get is random. Without a seed the draw uses the browser's cryptographically secure generator; with a seed it uses a small deterministic generator, which is reproducible and therefore explicitly not cryptographically secure.

For how randomness is produced across the whole site, see how Generate Random works.

Assumptions this tool makes

The client may send the same request more than once.
The server stores the result of a completed request against its key for some period.

Limitations and good to know

It covers the client and server contract, not a specific framework's implementation.
Key storage and expiry are described in general terms; the right retention depends on how long your clients retry.
It produces scenarios, not a conformance suite.
Nothing is stored between visits, so seed it if you need the same set.

Common mistakes

Generating the key inside the retry loop: A new key per attempt removes every protection the mechanism offers. This is the most common way idempotency is implemented and it does nothing.
Returning 409 for a legitimate retry: A client that did not hear the first response is behaving correctly. It should receive the original result, not an error.
Assuming one key protects a multi-step workflow: If the first attempt completed three of five steps, replaying from the start repeats three of them. Each step needs its own protection.

Practical tips

Generate the key with the intent, not with the attempt, and reuse it for every retry of that intent.
Make key retention longer than the client's maximum retry window, and write both numbers down.
Test two concurrent identical requests explicitly. A check-then-act with no lock passes every sequential test.

Privacy and your data

Everything runs in your browser. No keys, seeds or copied text are transmitted or stored between visits.

Frequently asked questions

What should the server return for a legitimate duplicate?: The stored result of the original request, with the original status. The client cannot tell it was a duplicate, which is the point.
How long should keys be kept?: Longer than your clients retry. If a job retries for a week and keys expire in a day, the protection silently stops applying before the retries do.
Does an idempotency key make everything safe?: No. It makes one call safe to repeat. A workflow of several calls needs each step to be safe, which is a separate piece of work.