Idempotent Requests

Idempotency is important in APIs because a resource may be called multiple times if an operation times out or encounters other server issues before it completes. If the original request and the subsequent retries are successful, the operation is completed multiple times. This means that you might create more resources than you intended.

To solve this problem, idempotent request identifiers are introduced to distinguish the first attempt from subsequent attempts. With an idempotent request, if the original request completes successfully, any subsequent retries complete successfully without performing any further actions.

Idempotency

An idempotent operation produces the same result even when the operation is repeated many times.

Idempotency in ECS APIs

When sending a request, the client can add X-Client-Token to the HTTP header as the idempotency identifier. For details, see Table 1.

**Table 1** Idempotency identifier message header
Parameter	Description	Mandatory	Example Value
X-Client-Token	Identifier that ensures idempotency of client requests It is a 32-bit UUID and is generated by the client. The value must be unique.	No	46436810-d999-454c-bd85-e515fd258600

Generally, the client resends the request only when the response status code is 5xx due to an internal server exception or connection timeout or when the response result cannot be obtained. If the retry request uses the same idempotent identifier and request parameters, the server will return the same result as the original request.

Description about idempotency identifiers:

An idempotency identifier is a case-sensitive 32-bit UUID in the format of xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (8-4-4-4-12), where each x is a hexadecimal number ranging from 0 to 9 or a to f. If you provide an identifier that is not in UUID format, the server returns error code Ecs.0123.
Idempotency identifiers must be unique. If you reuse an identifier with different parameters, the server returns error code Ecs.0122.
Idempotent identifiers remain valid for eight hours. If an identifier has expired, the server returns error code Ecs.0124.
After an idempotency identifier is used:
- If the returned status code is 2xx, subsequent retries will return the same result as the original one without affecting the server status.
- If the returned status code is 4xx, subsequent retries will fail. You need to rectify the fault based on the error information and retry the request.