更新时间：2024-12-03 GMT+08:00
请求幂等性说明
当您调用ECS API操作资源时，操作可能在完成之前超时或遇到其他服务器问题，客户端可能会尝试重试请求。如果原始请求和后续重试请求都成功执行，则操作将多次完成。这意味着您可能会创建比预期更多的资源。
为了解决这种问题，引入了请求幂等标识，通过针对幂等请求标识的一系列判断检查，服务端将识别当前请求是否为重试请求，进而进行下一步处理。
什么是请求幂等性
请求幂等性，指的是同样的请求被执行一次与连续执行多次的效果是一样的。换句话说就是，幂等方法不应该具有副作用（统计用途除外）。
如何保证请求幂等性
客户端在发送请求时，可以在HTTP请求消息头中增加X-Client-Token作为幂等性标识，字段描述参见表1。
|
名称 |
描述 |
是否必选 |
示例 |
|---|---|---|---|
|
X-Client-Token |
保证客户端请求幂等性的标识。 该标识为32位UUID格式，由客户端生成，且需确保不同请求之间该标识具有唯一性。 |
否 |
46436810-d999-454c-bd85-e515fd258600 |
通常情况下，客户端只需要在服务端内部异常、连接超时等响应状态码为5xx的错误，或者无法获取响应结果重试请求。重试请求仍然使用相同的幂等标识和请求参数，则服务端会返回与第一次请求相同的请求结果。
幂等标识的详细信息如下所示：
- 幂等标识是一个大小写敏感的32位UUID，其格式为：xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (8-4-4-4-12)，其中每个x是0-9或a-f范围内的一个十六进制的数字。如果您提供了一个非UUID格式的标识，则服务端会返回Ecs.0123错误码。
- 幂等标识需要具有唯一性，如果您提供了一个已经使用过的标识，但请求参数有变化，则服务端会返回Ecs.0122错误码。
- 幂等标识具有时效性（8小时），如果您提供了一个已经失效的标识，则服务端会返回Ecs.0124错误码。
- 使用幂等标识后：
- 返回结果状态码为2xx时，重试后客户端可以得到与上次相同的结果，但对您的服务端状态没有影响。
- 返回结果状态码为4xx时，重试不会成功。您需要根据错误信息排查问题后再重试请求。
父主题： 附录
