If a request timeout or an internal server error occurs when you call a Virtual Private Cloud (VPC) API operation, the client may retry the request. In this case, you can specify the ClientToken parameter in the request to prevent the system from performing the same operation multiple times.

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 a request is retried multiple times. Idempotence plays an important role in distributed system design.

Ensure idempotence

In most cases, a client retries a request only when the HTTP status code 500 (InternalServerError) is returned, the HTTP status code 503 (ServiceUnavailable) is returned, or when no response is returned. When you use the VPC 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 retries.

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 provide a used value for the ClientToken parameter and use different values for other request parameters, VPC returns the error code IdempotentParameterMismatch.
    Note You must use different values for SignatureNonce, Timestamp, and Signature in each retry. This is because VPC uses SignatureNonce to prevent replay attacks and uses Timestamp to mark the request time of each request. You must specify different SignatureNonce and Timestamp values in a retry. Consequently, the value of Signature is changed.
  • After you specify the ClientToken parameter in a request, the following results may be returned:
    • If the HTTP status code 200 is returned, the client will receive the same result as the last request after the request is retried. However, your server status will not be affected.
    • If an HTTP status code 4xx is returned without the try it later error message, a retry will fail. You must troubleshoot issues based on the returned error message before you retry a request.