Idempotency key
An idempotency key identifies retries of the same intended request. Scope, retention and API rules determine its effect.
An idempotency key is an identifier chosen by the client that lets a service recognise repeats of the same intended request. The aim is to avoid performing an already completed business action again on a retry. The API contract determines its precise effect.
Revisit a request with an uncertain outcome
In a fictional portal, the connection breaks after a request to create an order. Whether the ERP has already created the order is unclear. If the service supports this safeguard, the portal uses the same key for an appropriate retry. A new key could trigger another creation.
Follow the API's rules
Stripe describes different idempotency rules for API v1 and v2. The Idempotency-Key header is a provider-specific example. Check scope, retention and the handling of changed request data. The same key does not authorise arbitrary new content and is not, on its own, evidence of completed processing.
Sources
Related terms
- Event IDAn event ID identifies an event within an agreed scope. A repeat delivery needs to be distinguished from a new event.
- Webhook replayWebhook replay means sending a webhook notification again. Deliberate recovery and replay attacks require different checks.
- Transactional inboxA transactional inbox uses durable message records to protect local processing against duplicate deliveries.
- Message acknowledgementA message acknowledgement tells the broker that a delivery has been received or processed according to the agreed rule.
- Retry jitterRetry jitter varies waiting times randomly to spread retries and reduce simultaneous requests from many clients.
- Test tenantA logically bounded customer context of a multitenant application, configured for testing.
Articles on this topic
APIs & Integration with ASES
ERP, CRM and shop cleanly connected