What is Idempotency Key?
Turkish: Idempotency Key
An idempotency key is a unique token on retryable API requests that prevents duplicate payments, orders, or records.
What Is an Idempotency Key?
An idempotency key is a unique operation key used for API requests that may be retried, especially payments, order creation, and reservations. If the client sends the same operation again, the server recognizes the key and returns the previous result instead of starting a new operation.
In a typical flow, the client generates a UUID-like key and sends it in an Idempotency-Key header. The server stores that key with a request fingerprint and operation result for a limited period. If the network drops, the client times out, or the user clicks twice, the second request with the same key does not create a duplicate record.
Where It Is Used
Payment capture, money transfer, invoice creation, stock deduction, shipping-label generation, and ticket booking are common use cases. Read-only GET requests usually do not need this mechanism; the problem is retrying a write operation whose first outcome is uncertain.
Design Notes
Teams should define how long keys are retained, what happens if the same key arrives with a different request body, and how failed attempts are stored. This mechanism imitates idempotent behavior for operations that are not naturally safe to repeat, but it should still be backed by transaction handling and unique database constraints in the API.
Related Terms
An API is a contract that lets software systems request approved data or actions from one another through documented endpoints.
IdempotencyIdempotency ensures a repeated API or payment request produces one intended result instead of duplicating the operation.
IdempotentAn idempotent operation leaves the system in the same final state whether the same request runs once or several times.