Imagine a client creates an export job with POST /exports and sends an idempotency key. The client times out after sending the request. It cannot know whether the server created the job, so it retries with the same key.
1. Validate identity and input
The service authenticates the caller, authorizes the operation, validates the export parameters, and scopes the key to that caller and operation. The key should not allow one tenant to collide with or inspect another tenant's request.
2. Check prior state
The service looks up the idempotency record. If a completed matching request exists, it returns the recorded outcome. If the key exists with different parameters, the service rejects the reuse rather than silently treating it as the earlier intent.
3. Coordinate the side effect
For a new key, the service records an in-progress operation and performs the state change under a concurrency-safe contract. A database transaction can atomically write the job and completion record when both live in that database. If the effect crosses another service, an outbox, saga, or downstream idempotency contract may be needed; one local transaction cannot make a remote effect atomic.
4. Store and replay the outcome
The service persists the result and returns it. If the response is lost, a retry with the same key returns the same logical result instead of creating another job. Key retention, concurrent duplicate requests, and crash recovery are part of the API contract.
An idempotency key identifies one logical action across attempts. It is different from a trace ID, which connects telemetry for an execution. See the AWS Builders' Library discussion.