If a request times out or an internal server error occurs when you call a Resource Orchestration Service (ROS) API operation, the client may try to resend the request. In this case, you can specify the ClientToken parameter in the request to prevent repeated creation of stacks due to multiple retries.

What is idempotence?

In mathematical computing or computer science, idempotence describes an operation or resource that will have the same effect whether you request it once or multiple times. Idempotence plays an important role in distributed system design.

Ensure idempotence

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

ClientToken details

The following describes the details about the ClientToken parameter:

  • ClientToken is a unique and case-sensitive string that is generated by the client and cannot contain more than 64 ASCII characters, such as ClientToken=123e4567-e89b-12d3-a456-426655440000.
  • If you provide a used ClientToken while the other request parameters are different, ROS returns the error code IdempotentParameterMismatch.
    Note The parameters SignatureNonce, Timestamp, and Signature need to be changed during a retry, because ROS uses SignatureNonce to prevent replay attacks and uses Timestamp to mark the request time of each request. Therefore, a retried request requires different SignatureNonce and Timestamp values. This will also change the Signature value.
  • After the ClientToken parameter is added:
    • When HTTP status code 200 is returned, a retry generates the same result as the last time, without affecting your server status.
    • When HTTP status code 4xx is returned, the retry fails unless the error message indicates Try it later. You need to troubleshoot the error according to the error message, and then try again.

Idempotent request example

Take calling the CreateStack operation to create an ROS stack as an example. If you use the same ClientToken value while the other request parameters are the same, the server returns the same request result and generates only one StackId.

http(s)://ros.aliyuncs.com/? Action=CreateStack
&RegionId=cn-hangzhou
&StackName=MyStack
&Parameters.1.ParameterKey=InstanceId
&Parameters.1.ParameterValue=i-xxxxxx
&TimeoutInMinutes=10
&ClientToken=123e4567-e89b-12d3-a456-426655440000
&<Common request parameters>

If you do not use ClientToken, multiple stacks may be created when the server returns an error and the client sends the request again.

API operations

ClientToken is required when you call any of the following API operations: