When you call an AnalyticDB for PostgreSQL API operation, the request may time out or the server may return an error before the operation completes. If your client retries the request without any safeguard, the operation can run more than once—creating duplicate resources or triggering unintended side effects. Use the ClientToken parameter to make retry requests idempotent, so that multiple identical requests produce the same outcome as a single request.
How idempotence works
Idempotence is a property of some operations and resources in mathematics or computer science, and it is important to the design of distributed systems. An idempotent operation produces the same result no matter how many times it runs. To enable idempotence for an AnalyticDB for PostgreSQL API request, include a ClientToken value in the request. The client generates this token, and AnalyticDB for PostgreSQL uses it to detect duplicate requests and return the original result without repeating the operation.
Use ClientToken
ClientToken is a unique, case-sensitive string that you generate on the client side. It can contain up to 64 ASCII characters.
Example: ClientToken=123e4567-e89b-12d3-a456-426655440000
Include ClientToken in requests that may need to be retried—for example, when a request returns 500 Internal Server Error or 503 Service Unavailable, or when no response is received.
SignatureNonce, Timestamp, and Signature. AnalyticDB for PostgreSQL uses SignatureNonce to prevent replay attacks and Timestamp to identify when a request was made. Because both values change on each retry, Signature changes as well. Keep ClientToken the same across retries for the same logical request.Retry behavior by HTTP status code
| HTTP status code | Action | Details |
|---|---|---|
| 200 | Do not retry | The original request succeeded. Subsequent retries return the same result without modifying server state. |
4xx with try it later | Wait, then retry | The server is temporarily busy. Wait before retrying. |
| Other 4xx | Troubleshoot first | The request itself has a problem. Resolve the issue based on the error message before retrying. |
| 500 or 503 | Retry | A transient server-side error. Retry the request with the same ClientToken. |
Error: IdempotentParameterMismatch
If you reuse a ClientToken value but change other request parameters, AnalyticDB for PostgreSQL returns the IdempotentParameterMismatch error code. To resolve this, either reuse the original request parameters or generate a new ClientToken for the new request.