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

# 幂等性请求

当一个 API 调用或操作无论执行多少次都产生相同的结果时，我们称其为幂等。这确保了重复调用不会导致意外的副作用，从而防止意外的重复请求。

Fluz API 支持幂等性请求，以防止操作的意外重复。通过使用客户端生成的唯一幂等键，API 可确保在 10 分钟窗口内，如果提供相同的幂等键，则不会对同一请求进行多次处理。

## 工作原理

当请求中提供幂等键时：

* 服务器会缓存初始响应体及其状态码。
* 如果收到具有相同幂等键和响应码的重复请求，API 将返回缓存的结果，而不是重新执行操作，尤其是在操作中发生错误时。该机制通过在错误场景下仍返回一致结果来帮助防止意外的重复处理。

## 生成唯一的幂等键

客户端负责创建和刷新其幂等键。为确保唯一性：

* 我们强烈建议使用 V4 UUID，可通过如下库生成：[https://github.com/uuidjs/uuid](https://github.com/uuidjs/uuid)
* 作为最佳实践，幂等键应在一段时间后过期，以避免重用并确保请求唯一性。Fluz 会在 10 分钟后使每个唯一幂等键过期。

### 客户端需要：

1. 一个用于生成并存储新幂等键的操作
2. 一个根据客户端过期策略移除旧键的操作

## 必需的操作

并非所有 API 操作都需要幂等键。为确保以下关键操作的数据一致性，Fluz 要求使用幂等性：

* `purchaseGiftCard`（[在此查看](/purchase-gift-card)）
* `depositCashBalance`（[在此查看](/features/deposit-from-external-accounts)）

对于这些操作，必须提供 `idempotencyKey` 输入变量。

## 示例输入

```json theme={null}
{  
  "idempotencyKey": "2c29e5ad-bb36-4b7f-b012-b7d6031566e0",  
  "offerId": "2c29e5ad-bb36-4b7f-b012-b7d6031566e0",  
  "amount": 123.45,  
  "balanceAmount": 987.65,  
  "bankAccountId": "2c29e5ad-bb36-4b7f-b012-b7d6031566e0",  
  "bankCardId": "2c29e5ad-bb36-4b7f-b012-b7d6031566e0",  
  "paypalVaultId": "2c29e5ad-bb36-4b7f-b012-b7d6031566e0",  
  "exclusiveRateId": "2c29e5ad-bb36-4b7f-b012-b7d6031566e0",  
  "merchantSlug": "xyz789"  
}
```

<Note>
  Fluz 要求此操作提供幂等键。
</Note>

## 后续步骤

<CardGroup cols={2}>
  <Card title="购买礼品卡" icon="gift" href="/purchase-gift-card">
    在最常见的资金流转变更中查看幂等键的实际效果。
  </Card>

  <Card title="地址格式" icon="map-pin" href="/concepts/address-formatting-requirements">
    另一个常见的请求被拒原因——如何格式化地址以确保首次即可通过校验。
  </Card>
</CardGroup>

<StickyContactSalesBanner />