Clavem

Idempotency key

An idempotency key is a unique value a client sends with a request so that, if the same request is sent again after a timeout or error, the server performs the action once and returns the saved result instead of repeating it.

How it works

The word idempotent means that doing something twice has the same effect as doing it once. Setting a value is idempotent. Charging a card is not, unless the server is told that two requests are the same one.

The client generates a random key and sends it in a header. The server stores the key with the outcome of the first request. A retry with the same key returns that stored outcome and does not repeat the work.

Example: the double-submitted charge

A checkout script posts a payment request. The network drops before the response arrives, so the script cannot know if the charge happened.

Without a key, retrying risks charging the buyer twice. With one:

curl https://api.stripe.com/v1/customers \
  -u sk_test_...: \
  -H "Idempotency-Key: KG5LxwFBepaKHyUD" \
  -d description="My First Test Customer"

Send that exact request twice and Stripe creates one customer. Stripe’s documentation states the details as of November 2026, for API v1:

  • It saves the status code and body of the first request made with a key, once execution of the endpoint begins. Retries return the saved response, including 500 errors.
  • Keys can be removed automatically once they are at least 24 hours old. After that, reusing a key creates a new request.
  • The server compares the parameters of a retry with the original and returns an error if they differ, to catch accidental key reuse.
  • Requests that fail validation, or that collide with a request still running, are not saved. You can retry those.
  • All POST requests accept a key.

Idempotency key versus a unique constraint

A database unique constraint stops a duplicate row, but it throws an error on the second attempt, and the caller still does not know what the first attempt did. An idempotency key returns the first attempt’s result, which is what a retrying client wants. Use the key for the network boundary and the constraint as a second guard.

How Clavem handles it

The License API has no idempotency-key header. Clavem gets the same safety another way.

  • Stripe events. Every Stripe webhook event is processed once, keyed by its event id. A redelivered event, or one you replay, does not issue licenses again. See webhooks and Connecting Stripe.
  • Activation. Send a fingerprint with activate. Activating again with a fingerprint already active on that license returns the same seat, with its name updated, rather than using a second seat. The client can safely retry after a timeout.

If you call Stripe yourself from your backend, for example to create a checkout, send your own Idempotency-Key per logical purchase attempt.

Questions

What should an idempotency key look like?

Stripe suggests a V4 UUID or another random string with enough entropy to avoid collisions, up to 255 characters, and says to avoid sensitive data such as email addresses.

Do GET requests need an idempotency key?

No. Stripe says GET and DELETE requests are idempotent by definition, so a key has no effect on them. Keys matter for requests that create or change something.

Sources

  1. Stripe API Reference, Idempotent requests (checked November 2026)