# 幂等性与安全写入

> 在不产生重复数据的情况下重试创建请求，避免覆盖他人的编辑内容，并确保 Webhook 传递仅处理一次。

> Markdown version of https://kanorio.com/zh-CN/developers/basics/idempotency. Append `.md` to any developer docs URL for this format. Index: https://kanorio.com/llms.txt · MCP: https://app.kanorio.com/api/mcp
>
> Translated from the English original: https://kanorio.com/en/developers/basics/idempotency.md

网络请求可能会在中途失败。这三种机制让您可以在不产生重复数据或丢失他人工作成果的情况下进行重试。

## 幂等性令牌 (Idempotency keys)

重复执行成本较高的创建操作会接受 `Idempotency-Key` 标头。API 参考文件会标记这些操作，且 OpenAPI 文件会在这些操作上设置 `x-kanorio-idempotent: true`。

```bash
curl -X POST https://app.kanorio.com/api/v1/sites/ws_example123/collections/projects/items \
  -H "Authorization: Bearer $KANORIO_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: import-2026-11-02-row-17" \
  -d '{ "slug": "riverside-bakery", "fieldData": { "title": "Riverside Bakery" } }'
```

- 请自行选择令牌，长度为 1 到 200 个字符。UUID 或您系统中的 ID 均适用。
- 使用相同的令牌与相同的请求内容进行重试，将会返回原始结果，且不会创建任何新数据。
- 使用相同的令牌但不同的请求内容，将会返回 `409 IDEMPOTENCY_CONFLICT`。
- 若第一次请求仍在执行中，重试将会返回 `409 IDEMPOTENCY_IN_PROGRESS`。请稍候片刻后再试。
- 令牌的作用范围限于网站与该操作，并会在 24 小时后过期。

通过 MCP 时，请将令牌作为工具的 `idempotencyKey` 参数传递。

## 乐观并发控制 (Optimistic concurrency)

页面、全站页首与页尾，以及其他用户也会在后台编辑的内容，均使用乐观并发控制，以确保您的脚本不会在无意间覆盖他人的变更。

1. 读取资源并保留其时间戳：页面使用 `updatedAt`，全局内容使用 `contentUpdatedAt`。
2. 在写入时将其作为 `ifUnmodifiedSince` 传回。
3. 若资源在此期间已变更，写入将会失败并返回 `409 CONFLICT`，且 `details` 中会包含当前的时间戳。请重新读取、合并您的变更后再重试。

```json
{
  "ifUnmodifiedSince": "2026-11-02T08:00:00.000Z",
  "sections": [{ "id": "sec_hero_1", "type": "page-main-visual", "title": "Fresh bread daily" }]
}
```

API 参考文件会显示哪些操作支持 `ifUnmodifiedSince`。

## 草稿优先

大多数写入操作会变更草稿，并透过独立的发布操作使其生效。页面、全局内容与文章皆以此方式运作。集合项目会立即发布，除非您发送 `publish: false`。因此，失败或重复的写入几乎不会影响访客看到的内容。

## Webhook 传递

Kanorio 可能会多次传递相同的事件，例如在超时后，或当有人从后台重新发送时。每次传递都会带有一个 `X-Kanorio-Delivery` ID，该 ID 在重试过程中保持不变。请存储您已处理的 ID，并对重复的请求返回 `200`。请参阅 [Webhooks](https://kanorio.com/zh-CN/developers/webhooks)。