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

# 幂等性

> 在写入请求中使用稳定的 Idempotency-Key 标头，以便重试保持安全并进行去重。

# 幂等性

所有 `POST` 和 `PATCH` 变更（mutation）端点都接受可选的 `Idempotency-Key` 标头。

## 何时发送

在以下情况下使用幂等键：

* 客户端可能在传输失败后重试。
* 队列工作进程可能会多次派发同一个逻辑操作。
* AI 代理可能在部分进度完成后，因工具重试而重新运行一次变更操作。

## 推荐模式

* 每次逻辑变更生成一个稳定的键。
* 对该变更的重试复用同一个键。
* 当预期的变更发生变化时更换键。

## 示例

```http theme={null}
Idempotency-Key: create-project-song-1
```

```http theme={null}
Idempotency-Key: export-song-1
```

## 良好的边界划分

* 创建项目使用一个键。
* 导出该项目使用另一个键。
* 更新项目设置再使用另一个不同的键。

这样可以在保证重试安全的同时，避免误将不相关的工作去重。