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 AWS CLI commands also support idempotency by default.

Idempotent by default

• AssociateAddress

• CreateVpnConnection

• DisassociateAddress

• ReplaceNetworkAclAssociation

• TerminateInstances

The following API actions optionally support idempotency using a client token. The corresponding AWS 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.

Idempotent using a client token

• AllocateHosts

• AllocateIpamPoolCidr

• AssociateClientVpnTargetNetwork

• AssociateIpamResourceDiscovery

• AttachVerifiedAccessTrustProvider

• AuthorizeClientVpnIngress

• CopyFpgaImage

• CopyImage

• CreateCapacityReservation

• CreateCapacityReservationFleet

• CreateClientVpnEndpoint

• CreateClientVpnRoute

• CreateEgressOnlyInternetGateway

• CreateFleet

• CreateFlowLogs

• CreateFpgaImage

• CreateInstanceConnectEndpoint

• CreateIpam

• CreateIpamPool

• CreateIpamResourceDiscovery

• CreateIpamScope

• CreateLaunchTemplate

• CreateLaunchTemplateVersion

• CreateManagedPrefixList

• CreateNatGateway

• CreateNetworkAcl

• CreateNetworkInsightsAccessScope

• CreateNetworkInsightsPath

• CreateNetworkInterface

• CreateReplaceRootVolumeTask

• CreateReservedInstancesListing

• CreateRouteTable

• CreateTrafficMirrorFilter

• CreateTrafficMirrorFilterRule

• CreateTrafficMirrorSession

• CreateTrafficMirrorTarget

• CreateVerifiedAccessEndpoint

• CreateVerifiedAccessGroup

• CreateVerifiedAccessInstance

• CreateVerifiedAccessTrustProvider

• CreateVolume

• CreateVpcEndpoint

• CreateVpcEndpointConnectionNotification

• CreateVpcEndpointServiceConfiguration

• DeleteVerifiedAccessEndpoint

• DeleteVerifiedAccessGroup

• DeleteVerifiedAccessInstance

• DeleteVerifiedAccessTrustProvider

• DetachVerifiedAccessTrustProvider

• ExportImage

• ImportImage

• ImportSnapshot

• ModifyInstanceCreditSpecification

• ModifyLaunchTemplate

• ModifyReservedInstances

• ModifyVerifiedAccessEndpoint

• ModifyVerifiedAccessEndpointPolicy

• ModifyVerifiedAccessGroup

• ModifyVerifiedAccessGroupPolicy

• ModifyVerifiedAccessInstance

• ModifyVerifiedAccessInstanceLoggingConfiguration

• ModifyVerifiedAccessTrustProvider

• ProvisionIpamPoolCidr

• PurchaseHostReservation

• RequestSpotFleet

• RequestSpotInstances

• RunInstances

• StartNetworkInsightsAccessScopeAnalysis

• StartNetworkInsightsAnalysis

Types of idempotency

• Regional – Requests are idempotent in each Region. However, you can use the same request, including the same client token, in a different Region.

• Zonal – Requests are idempotent in each Availability Zone in a Region. For example, if you specify the same client token in two calls to AllocateHosts in the same Region, the calls succeed if they specify different values for the AvailabilityZone parameter.

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

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

Retry recommendations for idempotent requests

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 successfully.
400-series response codes (client errors)	Do not retry	There is a problem with the request, from among the following: It includes a parameter or parameter combination that is not valid. 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.