> ## 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` 헤더를 받습니다.

## 언제 보내야 하나요

다음과 같은 경우 멱등성 키를 사용하세요:

* 클라이언트가 전송(transport) 실패 후 재시도할 수 있는 경우.
* 큐 워커가 동일한 논리적 작업을 한 번 이상 디스패치할 수 있는 경우.
* AI 에이전트가 부분 진행 후 또는 도구 재시도로 변경 작업을 다시 실행할 수 있는 경우.

## 권장 패턴

* 논리적 변경 작업당 하나의 안정적인 키를 생성하세요.
* 해당 변경 작업의 재시도에는 동일한 키를 재사용하세요.
* 의도한 변경 작업이 바뀌면 키를 변경하세요.

## 예시

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

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

## 적절한 경계 설정

* 프로젝트 생성에는 하나의 키를 사용합니다.
* 해당 프로젝트 내보내기에는 다른 키를 사용합니다.
* 프로젝트 설정 업데이트에는 또 다른 키를 사용합니다.

이렇게 하면 서로 관련 없는 작업이 실수로 중복 제거되는 일을 막으면서도 재시도를 안전하게 처리할 수 있습니다.