> ## Documentation Index
> Fetch the complete documentation index at: https://developers.uqpay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 幂等请求

> 确保相同的请求只会被执行一次。

<h2 id="overview">概览</h2>

API 支持幂等性，确保在安全地重试请求的同时，不会意外重复执行同一个操作。通过使用幂等键，当出现连接错误时你可以安全地重发请求，而不会产生重复对象或多次执行更新。

<h2 id="how-idempotency-works">幂等机制如何工作</h2>

要发起幂等请求，请在请求头中额外携带 `x-idempotency-key` 字段。

<h3 id="key-management">幂等键管理</h3>

* 生成：客户端使用 `UUID` 生成唯一的幂等键。
* 生命周期：系统会在幂等键创建 `24` 小时后自动将其移除。

当请求携带通过 `UUID` 格式校验的幂等键时，无论请求成功还是失败，首次请求对应的状态码和响应体都会被保存。后续使用相同幂等键发起的请求将返回同样的结果，包括任何错误。

<h2 id="handling-requests">请求处理</h2>

幂等结果仅在端点开始执行后才会被保存。如果入参未通过校验、请求与另一个并发请求冲突，或者因网络问题导致 API 端点未能开始执行，则幂等结果不会被保存。在这些情况下，你可以安全地重试该请求。