# 멱등성 및 안전한 쓰기

> 중복 생성 없이 요청을 재시도하고, 다른 사람의 편집을 덮어쓰지 않으며, Webhook 전달을 정확히 한 번만 처리하는 방법을 설명합니다.

> Markdown version of https://kanorio.com/ko/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` 헤더를 허용합니다. 레퍼런스에서 해당 작업을 확인할 수 있으며, 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" }]
}
```

어떤 작업이 `ifUnmodifiedSince`를 지원하는지는 레퍼런스에서 확인할 수 있습니다.

## 초안 우선 방식

대부분의 쓰기 작업은 초안을 변경하며, 별도의 게시 작업을 통해 실제 반영됩니다. 페이지, 전역 콘텐츠, 게시물은 모두 이 방식으로 작동합니다. 컬렉션 항목은 `publish: false`를 보내지 않는 한 즉시 게시됩니다. 따라서 쓰기 작업이 실패하거나 반복되더라도 방문자가 보는 화면에는 거의 영향을 주지 않습니다.

## Webhook 전달

Kanorio는 타임아웃 발생 후나 관리 화면에서 누군가 다시 전송하는 경우 등 동일한 이벤트를 두 번 이상 전달할 수 있습니다. 모든 전달에는 재시도 시에도 동일하게 유지되는 `X-Kanorio-Delivery` ID가 포함됩니다. 처리한 ID를 저장하고 중복 요청에 대해서는 `200`을 반환하십시오. 자세한 내용은 [Webhooks](https://kanorio.com/ko/developers/webhooks)를 참조하십시오.