멱등성 및 안전한 쓰기

네트워크는 요청 도중에 실패할 수 있습니다. 다음 세 가지 메커니즘을 사용하면 중복을 생성하거나 다른 사람의 작업을 덮어쓰지 않고도 요청을 재시도할 수 있습니다.

멱등성 키(Idempotency keys)

반복 실행 시 비용이 발생하는 작업은 Idempotency-Key 헤더를 허용합니다. 레퍼런스에서 해당 작업을 확인할 수 있으며, OpenAPI 문서에는 x-kanorio-idempotent: true로 설정되어 있습니다.

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에 현재 타임스탬프가 포함됩니다. 다시 읽고 변경 사항을 병합한 후 재시도하십시오.

{
  "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를 참조하십시오.