| « PreviousNext » | |
   | Did this page help you? Yes | No | Tell us about it... |
Ensuring Idempotency
When you launch an instance through the API or the command line interface tools (CLI), you can optionally provide a client token to ensure the request is idempotent. If timeouts or connection errors occur, you can repeat the request and be sure you haven't launched more instances than you intended. The token must be a unique, case-sensitive string of up to 64 ASCII characters.
If you repeat the request with the same client token, the same response is returned for each repeated request. The only information that might vary in the response is the state of the instance (e.g., pending). The client token is included in the response when you describe the instance.
If you repeat the request with the same client token, but change another request
parameter, Amazon EC2 returns an IdempotentParameterMismatch error.
The client token is valid for at least 24 hours after the termination of the instance. You should not reuse a client token for another call later on.
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 you use the same exact call (with the same client token) in each of the other regions, the result is a different running instance in each region.
The following table shows common response codes and the recommended course of action.
| Code | Retry | Comments |
|---|---|---|
|
200 (OK) |
No effect |
After you receive a 200, the request has succeeded and any further retries have no effect. |
|
400 (Client Error) |
Not recommended |
A 400 response typically indicates the request will never succeed (for example when a specified parameter value is not valid). In certain specific cases relating to resources that are transitioning between states, a repeat of the request could possibly succeed (e.g., launching an instance against an Amazon EBS volume that is currently transitioning to the available state). |
|
500 (Server Internal Error) |
Recommended |
These errors are generally transient. Repeat the request with an appropriate back-off strategy. |
|
503 (Server Unavailable) |
Recommended |
These errors can occur in times of extreme load. Repeat the request with an appropriate back-off strategy. |
Command Line Tools
Use the ec2-run-instances command.
API
Use the RunInstances action.
To send an idempotent request to launch instances
Add the
ClientTokenparameter to your Query request with a unique, case-sensitive string of up to 64 ASCII characters.https://ec2.amazonaws.com/ ?Action=RunInstances &ImageId=ami-3ac33653 ... &ClientToken=550e8400-e29b-41d4-a716-446655440000 &AUTHPARAMS
