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

# 幂等键

> 在 POST 请求上通过 X-Idempotency-Key 防止重复提交

## 为什么需要

超时或不确定的 `5xx` 后常会重试。若没有幂等键，服务端可能把每次重试当成**新请求** — 产生重复任务、多扣积分或重复 Webhook。

`X-Idempotency-Key` 标识同一次业务提交。在同一 API Key 下，相同路径 + Key 在 TTL 内（默认 **24 小时**）只接受一次。**相同意图的重试用同一个 Key**；新任务用**新 Key**。

<Info>
  幂等防的是**同一次提交的重复投递**，不是禁止发起两次不同的任务。
</Info>

## 怎么用

对 Open API 的**每一个 `POST` 请求**（`/openapi/v1/**`）都加上该请求头：

```http theme={null}
X-Idempotency-Key: <unique-string>
```

规则：

* 去空格后非空，最长 **64** 字符
* 在**第一次请求前**生成 Key，并随本次尝试保存，便于安全重试
* 不要用同一 Key 提交不同内容的请求 — 会返回 `409 Conflict`

## Key 已被占用时

* HTTP `409 Conflict`
* 响应头 `Retry-After: 2`
* 响应体：`code: 409`，`message` 含 `Idempotency key already used`

## 安全重试 vs 新任务

| 场景          | Key        |
| ----------- | ---------- |
| 首次提交        | 新的唯一 Key   |
| 超时后重试（相同意图） | **相同 Key** |
| 新任务或新写入     | **新 Key**  |

## 示例

```bash theme={null}
export IDEM_KEY="job-$(date +%s)-$RANDOM"

curl -X POST "https://api.vmeg.ai/openapi/v1/task/tts/create" \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Idempotency-Key: $IDEM_KEY" \
  -H "Content-Type: application/json" \
  -d @payload.json
```

<Tip>
  若结果不确定，用**同一个 Key** 重试。不要在每次重试时换新 Key，否则可能重复写入。
</Tip>