Ensuring idempotency in Amazon EC2 API requests

When you make a mutating API request, the request typically returns a result before the operation's asynchronous workflows have completed. Operations might also time out or encounter other server issues before they complete, even though the request has already returned a result. This could make it difficult to determine whether the request succeeded or not, and could lead to multiple retries to ensure that the operation completes successfully. However, if the original request and the subsequent retries are successful, the operation is completed multiple times. This means that you might create more resources than you intended.

Idempotency ensures that an API request completes no more than one time. With an idempotent request, if the original request completes successfully, any subsequent retries complete successfully without performing any further actions. However, the result might contain updated information, such as the current creation status.

Idempotency in Amazon EC2

The following API actions are idempotent by default, and do not require additional configuration. The corresponding Amazon CLI commands also support idempotency by default.

The following API actions optionally support idempotency using a client token. The corresponding Amazon CLI commands also support idempotency using a client token. A client token is a unique, case-sensitive string of up to 64 ASCII characters. To make an idempotent API request using one of these actions, specify a client token in the request. You should not reuse the same client token for other API requests. If you retry a request that completed successfully using the same client token and the same parameters, the retry succeeds without performing any further actions. If you retry a successful request using the same client token, but one or more of the parameters are different, other than the Region or Availability Zone, the retry fails with an IdempotentParameterMismatch error.

RunInstances idempotency

The RunInstances API action uses both Regional and zonal idempotency.

The type of idempotency that is used depends on how you specify the Availability Zone in your RunInstances API request. The request uses zonal idempotency in the following cases:

If you do not explicitly or implicitly specify an Availability Zone, the request uses Regional idempotency.

Zonal idempotency

Zonal idempotency ensures that a RunInstances API request is idempotent in each Availability Zone in a Region. This ensures that a request with the same client token can complete only once within each Availability Zone in a Region. However, the same client token can be used to launch instances in other Availability Zones in the Region.

For example, if you send an idempotent request to launch an instance in the us-east-1a Availability Zone, and then use the same client token in a request in the us-east-1b Availability Zone, we launch instances in each of those Availability Zones. If one or more of the parameters are different, subsequent retries with the same client token in those Availability Zones either return successfully without performing any further actions or fail with an IdempotentParameterMismatch error.

Regional idempotency

Regional idempotency ensures that a RunInstances API request is idempotent in a Region. This ensures that a request with the same client token can complete only once within a Region. However, the exact same request, with the same client token, can be used to launch instances in a different Region.

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 the eu-west-1 Region, we launch instances in each of those Regions. If one or more of the parameters are different, subsequent retries with the same client token in those Regions either return successfully without performing any further actions or fail with an IdempotentParameterMismatch error.

Examples

Amazon CLI command examples

To make an Amazon CLI command idempotent, add the --client-token option.

Example 1: Idempotency

The following allocate-hosts command uses idempotency as it includes a client token.

aws ec2 allocate-hosts  --instance-type m5.large  --availability-zone eu-west-1a  --auto-placement on  --quantity 1 --client-token 550e8400-e29b-41d4-a716-446655440000

Example 2: run-instances regional idempotency

The following run-instances command uses regional idempotency as it includes a client token but does not explicitly or implicitly specify an Availability Zone.

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

Example 3: run-instances zonal idempotency

The following run-instances command uses zonal idempotency as it includes a client token and an explicitly specified Availability Zone.

aws ec2 run-instances  --placement "AvailabilityZone=us-east-1a" --image-id ami-b232d0db --count 1 --key-name my-key-pair --client-token 550e8400-e29b-41d4-a716-446655440000

API request examples

To make an API request idempotent, add the ClientToken parameter.

Example 1: Idempotency

The following AllocateHosts API request uses idempotency as it includes a client token.

https://ec2.amazonaws.com.cn/?Action=AllocateHosts
&AvailabilityZone=us-east-1b
&InstanceType=m5.large
&Quantity=1
&AutoPlacement=off
&ClientToken=550e8400-e29b-41d4-a716-446655440000
&AUTHPARAMS

Example 2: RunInstances regional idempotency

The following RunInstances API request uses regional idempotency as it includes a client token but does not explicitly or implicitly specify an Availability Zone.

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

Example 3: RunInstances zonal idempotency

The following RunInstances API request uses zonal idempotency as it includes a client token and an explicitly specified Availability Zone.

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

Retry recommendations for idempotent requests

The following table shows some common responses that you might get for idempotent API requests, and provides retry recommendations.