If a request times out or an internal error occurs on the server when you call the Resource Orchestration Service (ROS) API, the client may attempt to send a retry 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 and resources in mathematics or computer science. Idempotence allows you to obtain the result of the initial request after you perform operations or apply resources multiple times. Idempotence is important to the design of distributed systems.

Ensure idempotence

In most cases, a client sends a retry request when the returned HTTP status code is 500 Internal Server Error or 503 Service Unavailable, or when no result is returned. When you call the ROS API, you can specify a parameter so that your client can generate a string that contains up to 64 ASCII characters in length, and specify the string as the value of the ClientToken parameter to ensure the idempotence of the retry request.

ClientToken

The following information describes the ClientToken request parameter:

  • The value of the ClientToken parameter 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-42665544****.
  • If a retry request contains the same ClientToken value as the initial request but contains different values of some other parameters, ROS returns the InvalidIdempotenceParameter error code.
    Note The values of the SignatureNonce, Timestamp, and Signature parameters in a retry request must be changed. In the ROS API, the SignatureNonce parameter prevents replay attacks and the Timestamp parameter records the time of each request. Therefore, the values of the SignatureNonce and Timestamp parameters in each retry request must be different from the values in the initial request. By default, the value of the Signature parameter is changed when you change the values of the SignatureNonce and Timestamp parameters.
  • After you specify the ClientToken parameter in a retry request, the following results may be returned:
    • The HTTP status code 200 OK that indicates a successful call is returned. In this case, the client can obtain the same result as the initial request. The server is not affected.
    • The HTTP status code that indicates a failed call such as 400 Bad Request is returned. In this case, the retry request fails if an error message such as try it later appears. You can identify the causes of the errors based on the error messages and send another retry request.

Sample requests

In this example, the CreateStack operation is called to create a stack in a retry request. If you set the ClientToken request parameter to the ClientToken value contained in the initial request and do not change the values of other request parameters, the StackId value returned by the server is the same as that in the initial request. If you set the ClientToken parameter to a value that is different from the one in the initial request, the server may return different values for the StackId parameter and create multiple stacks.

Sample requests

http(s)://ros.aliyuncs.com/?Action=CreateStack
&RegionId=cn-hangzhou
&StackName=MyStack
&TemplateBody={"ROSTemplateFormatVersion": "2015-09-01"}
&ClientToken=123e4567-e89b-12d3-a456-42665544****
&<Common request parameters>

Sample responses

{
    "StackId": "4a6c9851-3b0f-4f5f-b4ca-a14bf691****",
    "RequestId": "B288A0BE-D927-4888-B0F7-B35EF84B6E6F"    
}