If a request timeout or an internal server error occurs when you call an ECS API operation, the client may attempt to resend the request. In this case, you can specify the ClientToken parameter in the request to prevent the client from repeatedly sending the request.

What is idempotence

Idempotence is a property of some operations or resources in mathematics and computer science. It means that an operation or resource leads to the same result, regardless of how many requests are sent. Idempotence plays an important role in the distributed system design.

Ensure idempotence

Typically, the client needs to retry a request only when error 500 (InternalError) or 503 (ServiceUnavailable) is returned or when no response is received. When you use Alibaba Cloud ECS API, the client generates a parameter value that consists of up to 64 ASCII characters, and you can assign the value to ClientToken to ensure the idempotence of the retried requests.

ClientToken details

The following section describes the details about ClientToken:

  • The ClientToken value is a unique and case-sensitive string that is generated by a client and can contain up to 64 ASCII characters in length. Example: ClientToken=123e4567-e89b-12d3-a456-426655440000.
  • If you specify a request with a ClientToken value that is in use but with different request parameters, ECS returns the IdempotentParameterMismatch error code.
    Note You must change the values of SignatureNonce, Timestamp, and Signature when you retry an API request. This is because ECS uses SignatureNonce to prevent replay attacks and uses Timestamp to record the timestamp of each request. Therefore, you must specify different SignatureNonce and Timestamp values in a retried request. Consequently, this changes the value of Signature.
  • After you add the ClientToken parameter to a retried request:
    • If an HTTP status code 200 is returned, the retry generates the same result as the last request and your server status is not affected.
    • If an HTTP status code 4xx is returned, the retry fails. If the status code is returned with the try it later error message, the server is busy. Try again later. You must troubleshoot problems based on the returned error message before you resend a request.

Sample idempotent requests

For example, assume that you call the RunInstance operation to create an ECS instance. If you use the same ClientToken value while keeping other request parameters unchanged, the server returns the same response and generates only one InstanceId value. 

https://ecs.aliyuncs.com/?Action=RunInstances
&RegionId=cn-hangzhou
&InstanceType=ecs.cm4.6xlarge
&ImageId=win2008r2_64_ent_sp1_en-us_40G_alibase_20170915.vhd
&SecurityGroupId=sg-securitygroupid
&Amount=1
.......
&ClientToken=123e4567-e89b-12d3-a456-426655440000
&<Common request parameters>

If you do not use ClientToken, multiple ECS instances may be created when the client retries operations after errors occur.

API operations