Ensure Idempotence

Last Updated: Jun 07, 2016

  • When you call the “create instance” interface to create ECS in Server Load Balancer, if request timeout or server internal error occurs, the client may attempt to resend the request. Now, the client may provide an optional parameter ClientToken to prevent the server from creating more instances than expected instances, i.e. providing the ClientToken parameter to ensure idempotence of the requests. ClientToken is a unique case-sensitive string created by the client and it contains no more than 64 ASCII characters.

  • If the user uses the same ClientToken value to call the “create instance” interface, the server will return the same result of the request containing the same InstanceId. Thus, if the user sees an error and retries, he can provide the same ClientToken value to guarantee that Server Load Balancer creates only one instance and obtain the InstanceId of the instance.

  • If the user provides a used ClientToken while the other request parameters are different, Server Load Balancer will return the error code IdempotentParameterMismatch. Attention: the parameters SignatureNonce, Timestamp and Signature need to be changed during a retry, because Server Load Balancer uses SignatureNonce to prevent replay attack and uses Timestamp to mark the request time of each request. Therefore, a reattempted request requires different SignatureNonce and Timestamp values, for this will change the Signature value.

  • Usually, the client only needs to retry if the error 500 (InternalError) or 503 (ServiceUnavailable) occurs, or no response is obtained. If the return result is 200, a retry will obtain the same result, but the server status will not be affected. For the 4xx return error, the retry does not work either usually.

Thank you! We've received your feedback.