If a request timeout or an internal server error occurs when you call an Elastic Compute Service (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
IdempotentParameterMismatcherror code. You can change the ClientToken value and retry.When you reuse a ClientToken value and leave other parameters unchanged in a request, the client receives a response that same as the first time the request was sent, which does not affect the status of your server-side ECS instance.
NoteYou must change the values of SignatureNonce, Timestamp, and Signature when you retry an API request. This is because ECS uses SignatureNonce to ensure that each request is unique and 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 latererror 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. If you cannot create an instance due to insufficient instance resources, resolve the insufficient resource issue, change a ClientToken value, and then create an instance.
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
The following section lists some API operations that include ClientToken for your reference. For information about whether an API operation includes ClientToken, see the topic that describes the API operation.