This topic describes how to ensure idempotence by specifying the ClientToken parameter. When you make VPC API calls, operations might time out or encounter server issues before they complete, and thus lead to multiple retries. You can specify the ClientToken parameter when you make a request to avoid subsequent retries.

What is idempotence?

In mathematics and computer science, idempotence is the property of certain operations that allows you to retry a request multiple times while only performing the action once. Idempotence plays an important role in the design of distributed systems.

Ensure idempotence

Generally, a client will make a retry when a 500 (InternalError) or 503 (ServiceUnAvailable) error occurs or it does not receive a response. You can make Alibaba Cloud VPC API calls for the client to generate a string of up to 64 ASCII characters, which is assigned to ClientToken to ensure idempotence.

ClientToken

The details of ClientToken are described as follows:

  • A ClientToken is a unique, case-sensitive string of up to 64 ASCII characters. For example, ClientToken=123e4567-e89b-12d3-a456-426655440000.
  • If you make an API request with the same ClientToken that is already specified for another API request, even if with other parameters being different, the VPC returns the error IdempotentParameterMismatch.
    Note The values for the parameters including SignatureNonce, TimeStamp, and Signature cannot be the same each time a request is resent. SignatureNonce is included to mitigate potential replay attacks. Timestamp marks the sending time of a request. Therefore, the values of SignatureNonce and Timestamp must be different if you retry a request. This also changes the value of Signature.
  • After specifying the ClientToken parameter:
    • When the HTTP status code 200 is returned, any subsequent retries return the result from the original successful request and they have no additional effect.
    • However, when the HTTP status code 4xx is returned, the retry will fail if try it later or similar errors do not occur. You must troubleshoot the error according to the error message and try again.