Idempotency

Idempotency-Key: signup-8f21c0

Repeating a key within the idempotency window returns the original result rather than starting a second verification. The window is 30 minutes.

Use it on anything a user can double-submit

A signup form that a browser retried, a queue consumer that redelivered, a mobile client on a flaky connection — all of them produce the same question twice, and without a key the second one is a second verification: a second SMTP session to somebody’s mail server, a second charge, and a second identifier for one conclusion.

Derive the key from what makes the request unique in your system — the signup attempt, the row, the job — and not from the address. Two different people signing up with the same address are two questions.

What it is not

It is not a cache and it does not make repeated verification free. It makes one request repeatable.

The service does have a result cache, and it is a separate mechanism: an address that has been verified is not verified again for at least a day, and a repeat inside that window is answered from the earlier conclusion. Two things to know about it:

• A cached answer keeps the original identifier, because it is the same conclusion and the same conclusion keeps the same name. freshness tells you when the evidence was actually gathered — see Confidence.
• A cache hit is charged. The cache is our optimisation, not your discount: what you buy is the decision, and you got one.

What happens without a key

Nothing refuses the request. You get a fresh verification with a fresh identifier, which is the correct behaviour for a genuinely new question and the wrong one for a retry. The header is optional because the service cannot tell the two apart and will not guess.