Menu
Amazon Elastic Compute Cloud
API Reference (API Version 2016-09-15)

Ensuring Idempotency

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 pending to 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.

Client Tokens

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 IdempotentParameterMismatch error.

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.

CodeRetryComments

200 (OK)

No effect

The request has succeeded and any further retries have no effect.

400 (Client Error)

Not recommended

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 available).

500 (Server Internal Error)

Recommended

The error is generally transient. Repeat the request with an appropriate backoff strategy.

503 (Server Unavailable)

Recommended

The error can occur when there is extreme load. Repeat the request with an appropriate backoff strategy.

Idempotency Support

The following commands and actions are idempotent:

AWS CLI Idempotent Commands

  • associate-address

  • create-vpn-connection

  • disassociate-address

  • terminate-instances

Query API Idempotent Actions

  • AssociateAddress

  • CreateVpnConnection

  • DisassociateAddress

  • TerminateInstances

The following commands and actions support idempotent operations using a client token:

AWS CLI Commands with a --client-token Option

  • allocate-hosts

  • copy-image

  • create-flow-logs

  • create-nat-gateway

  • create-reserved-instances-listing

  • create-route

  • create-vpc-endpoint

  • import-image

  • import-snapshot

  • modify-reserved-instances

  • request-spot-fleet

  • request-spot-instances

  • run-instances

Query API Actions with a ClientToken Parameter

  • AllocateHosts

  • CopyImage

  • CreateFlowLogs

  • CreateNatGateway

  • CreateReservedInstancesListing

  • CreateRoute

  • CreateVpcEndpoint

  • ImportImage

  • ImportSnapshot

  • ModifyReservedInstances

  • RequestSpotFleet

  • RequestSpotInstances

  • RunInstances

Example Idempotent Command

To make a command an idempotent request, add the --client-token option. The client token is a unique, case-sensitive string of up to 64 ASCII characters.

AWS CLI

Use the run-instances command as follows to make an idempotent request:

aws ec2 run-instances --image-id ami-b232d0db --count 1 --key-name my-key-pair --client-token 550e8400-e29b-41d4-a716-446655440000

Amazon EC2 CLI

Use the ec2-run-instances command as follows to make an idempotent request:

ec2-run-instances ami-b232d0db -k my-key-pair --client-token 550e8400-e29b-41d4-a716-446655440000

Example Idempotent Query

Use the RunInstances action as follows to make an idempotent request:

https://ec2.amazonaws.com/?Action=RunInstances
&ImageId=ami-3ac33653
&MaxCount=1
&MinCount=1
&KeyName=my-key-pair
&ClientToken=550e8400-e29b-41d4-a716-446655440000
&AUTHPARAMS

The ClientToken parameter requires a unique, case-sensitive string of up to 64 ASCII characters.