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

Ensuring Idempotency

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, all subsequent retries return the result from the original successful request and they have no additional effect.

Idempotency in Amazon EC2

In Amazon EC2, some API actions are idempotent by default, and do not need any additional configuration.

Other API actions optionally support idempotency using a client token. A client token is a unique, case-sensitive string of up to 64 ASCII characters that you specify when you make a mutating API request. When you make an idempotent API request using one of these actions, you specify a client token that is unique to that request. You should not reuse the same client token for other API requests. If you retry an API request with the same client token and the same parameters after it has completed successfully, the result of the original request is returned. If you retry a request with the same client token, but change one or more of the API parameters, the IdempotentParameterMismatch error is returned.

The following tabs list the API actions that support idempotency by default, and those that support idempotency using a client token.

Note

This information also applies to the equivalent AWS CLI commands.

Idempotent by defaultIdempotent using a client token
Idempotent by default

The following API actions are idempotent by default and do not need a client token:

  • AssociateAddress

  • CreateVpnConnection

  • DisassociateAddress

  • ReplaceNetworkAclAssociation

  • TerminateInstances

Idempotent using a client token

The following API actions support idempotency using a client token:

  • AllocateHosts

  • CopyImage

  • CreateEgressOnlyInternetGateway

  • CreateFlowLogs

  • CreateFpgaImage

  • CreateNatGateway

  • CreateReservedInstancesListing

  • CreateRoute

  • CreateVpcEndpoint

  • ImportImage

  • ImportSnapshot

  • ModifyReservedInstances

  • PurchaseHostReservation

  • PurchaseScheduledInstances

  • RequestSpotFleet

  • RequestSpotInstances

  • RunInstances

  • RunScheduledInstances

RunInstances Idempotency

The RunInstances API action uses two types of idempotency: regional and zonal.

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 explicitly specify an Availability Zone using the AvailabilityZone parameter in the Placement data type

  • If you implicitly specify an Availability Zone using the SubnetId parameter

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 the result of original request or the 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 the result of original request or the IdempotentParameterMismatch error.

Tip

If one of the Availability Zones in the requested Region is not available, RunInstances requests that use regional idempotency could fail. To leverage the Availability Zone features offered by the AWS infrastructure, we recommend that you use zonal idempotency when launching instances. RunInstances requests that use zonal idempotency and target an available Availability Zone succeed even if another Availability Zone in the requested Region is not available.

Examples

AWS CLI Command Examples

To make an AWS 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/?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/?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/?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

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

Response Recommendation Comments

200 (OK)

Do not retry

The original request completed successfully. Any subsequent retries return the result from the original successful request and they have no additional effect.

400-series response codes (client errors)

Do not retry

There is a problem with the request, from among the following:

  • It includes an invalid parameter or parameter combination.

  • It uses an action or resource for which you do not have permissions.

  • It uses a resource that is in the process of changing states.

If the request involves a resource that is in the process of changing states, retrying the request could possibly succeed.

500-series response codes (server errors)

Retry

The error is caused by an AWS server-side issue and is generally transient. Repeat the request with an appropriate backoff strategy.