Idempotency
Objective
Section titled “Objective”Networks fail after the server has acted and before the client has heard. Anything that creates or destroys must therefore be safe to retry, or a lost response becomes a duplicate resource and a duplicate charge.
Read this page before writing any automated caller.
Requirements
Section titled “Requirements”- None
Instructions
Section titled “Instructions”Client tokens
Section titled “Client tokens”An operation that accepts a ClientToken takes a value the caller chooses,
unique to that logical request.
If a request arrives with a token already seen:
- and the parameters are identical, the original result is returned and nothing new is created;
- and the parameters differ, the request is refused with
IdempotentParameterMismatch.
The mismatch case exists so that a bug in a caller — reusing a token while changing what it asks for — surfaces as an error rather than as a silent duplicate.
PROPOSED: tokens are up to 64 ASCII characters and are remembered for 24 hours. After that a repeated token is treated as new.
PROPOSED: a UUID is the recommended token. The documentation says so rather than leaving each caller to invent a scheme.
Which operations accept a token
Section titled “Which operations accept a token”Only those whose mirrored AWS model declares one.
This is a hard constraint rather than a style choice. The AWS SDKs validate parameters against their own bundled service model before sending anything. A token added to an operation that AWS does not model with one is rejected by the client with a parameter-validation error, and the request never leaves the customer’s machine. Mandating a token everywhere would mandate something customers cannot send.
RunInstances accepts one. CreateSecurityGroup, CreateKeyPair,
CreateTags and CreateVolume do not, because Amazon EC2’s 2016-11-15 model
does not declare one for them.
Services with no AWS counterpart — Billing, Account — are free to require a
token, and PlaceOrder does require one, because it is the operation that
spends money.
Each operation’s reference page states which case it is in.
Where an operation has no token
Section titled “Where an operation has no token”Retry safety comes from the operation’s own semantics, and each reference page says which applies:
- Absolute writes.
CreateTagssets tags to the values given; repeating it changes nothing. - Deletes. See below.
- Neither.
CreateKeyPairgenerates a new key pair each time it is called. A retry after a lost response produces a second key pair, which is untidy but not billable. The reference page says so plainly.
Deletes
Section titled “Deletes”A delete returns the mirrored AWS error when the resource does not exist. It does not report success.
This is worth stating precisely because the opposite convention is tempting and wrong. Infrastructure tooling — the Terraform AWS provider among others — polls for a not-found error to confirm that a destroy has completed, and treats not-found during a refresh as “deleted out of band”. A server that always reported success for a delete would leave that tooling unable to distinguish “gone” from “not yet gone”, producing hung destroys and permanent state drift.
Retry safety for deletes therefore belongs to the client: a caller retrying a delete treats the not-found error as success. That is what the SDKs and provider already do.
Interaction with billing
Section titled “Interaction with billing”An idempotent replay never produces a second billable resource and never opens a second usage stream. Usage records are written against the resource over time, not against the request that created it, so a replayed request that creates nothing meters nothing.
Always safe, always repeatable. A read is never rate-limited into failure by being repeated, only throttled.