An idempotent operation completes no more than one time.
When you launch an instance, the request typically returns before the operation has
completed. You determine whether the operation was successful by monitoring the state of
the instance (it goes from
running). If the
operation times out or there are connection issues, you might need to retry the request.
However, if the original request and a retry are both successful, you'll end up with more
instances than you intended to launch.
If you launch your instance using run-instances (AWS CLI), ec2-run-instances (Amazon EC2 CLI), or RunInstances, you can optionally provide a client token to ensure that the request is idempotent. If you repeat a request, the same response is returned for each repeated request. The only information that might vary in the response is the state of the instance.
A client token is a unique, case-sensitive string of up to 64 ASCII characters. It is included in the response when you describe the instance. A client token is valid for at least 24 hours after the termination of the instance. You should not reuse a client token in another call later on.
If you repeat a request with the same client token, but change another request
parameter, Amazon EC2 returns an
You can use the same client token for the same request across different
regions. For example, if you send an idempotent request to launch an instance in the
us-east-1 region, and then use the same client token in a request in other regions,
we'll launch instances in each of those regions.
The following table shows common response codes and the recommended course of action.
The request has succeeded and any further retries have no effect.
400 (Client Error)
The request will never succeed (for example, a specified parameter value is not
valid). If the request involves a resource that is in the process of
changing states, repeating the request could possibly succeed (for
example, launching an instance using an Amazon EBS volume that is
about to become
500 (Server Internal Error)
The error is generally transient. Repeat the request with an appropriate backoff strategy.
503 (Server Unavailable)
The error can occur when there is extreme load. Repeat the request with an appropriate backoff strategy.
The following commands and actions are idempotent:
AWS CLI Idempotent Commands
Query API Idempotent Actions
The following commands and actions support idempotent operations using a client token:
AWS CLI Commands with a --client-token Option
Query API Actions with a ClientToken Parameter
Example Idempotent Command
To make a command an idempotent request, add the
The client token is a unique, case-sensitive string of up to 64 ASCII characters.
Use the run-instances command as follows to make an idempotent request:
aws ec2 run-instances --image-id
ami-b232d0db--count 1 --key-name
Amazon EC2 CLI
Use the ec2-run-instances command as follows to make an idempotent request:
Example Idempotent Query
Use the RunInstances action as follows to make an idempotent request:
ami-3ac33653&MaxCount=1 &MinCount=1 &KeyName=
ClientToken parameter requires a unique,
case-sensitive string of up to 64 ASCII characters.