idempotency key

A unique value a client sends with a non-idempotent request, such as a create, so the server can recognise a retry and return the original result instead of acting twice.

In more detail

The server stores the key, a fingerprint of the request and the first response. A retry with the same key and body gets the same status, Location and body instead of a second resource. Reusing a key with a different body is rejected: the IETF draft recommends 422, and many services use 409 Conflict. Keys are scoped to the caller and expire after a documented period.

Example

In the APIs course: the fault 03-non-idempotent-retry makes two retries with one key create two tasks, and the service answers 409 for a reused key with a changed body.

Related terms

Taught in

References