If a request timeout or an internal server error occurs when you call an AnalyticDB for PostgreSQL API operation, the client may attempt to resend the 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 use AnalyticDB for PostgreSQL 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 retried requests.

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 specify a request with a ClientToken value that is in use but with different request parameters, AnalyticDB for PostgreSQL returns the IdempotentParameterMismatch error code.
    Note If you call the operation again, you must change the values of the SignatureNonce, Timestamp, and Signature parameters. This is because AnalyticDB for PostgreSQL uses the SignatureNonce parameter to prevent replay attacks and uses the Timestamp parameter to identify the timestamp of each request. Therefore, a retry request requires different values of the SignatureNonce and Timestamp parameters. In this case, the value of the Signature parameter changes.
  • If you specify the ClientToken parameter and the request fails, the request is resent based on the following HTTP status codes and error messages:
    • If an HTTP status code 200 is returned, the retry generates the same result as the last request and your server status is not affected.
    • If an HTTP status code 4xx is returned, the retry fails. If the status code is returned with the try it later error message, the server is busy. Try again later. You must troubleshoot problems based on the returned error message before you resend a request.