🗝️ 멱등성 키 설계 가이드 | 중복 요청 어떻게 막을까?

멱등성 키를 쓰는 요청 수

건/초

키·응답 보관 기간

시간

공인된 권장 보관 기간은 없습니다. 클라이언트가 재시도를 포기하는 시점보다 길게 잡아야 같은 키의 재요청을 알아볼 수 있습니다.

키 문자 집합

키 길이 (UUID 선택 시 사용하지 않음)

자

재생용으로 저장할 응답 크기 (선택)

충돌 확률은 생일 문제 근사식 키 수² ÷ (2 × 키 공간) 으로 계산한 상한에 가까운 값입니다. 키를 난수로 만들 때의 값이므로, 요청 본문을 해시해 키로 쓰면 본문이 같은 서로 다른 요청이 같은 키가 되는 별개의 문제가 생깁니다.

멱등성 키는 길이보다 범위와 보관 기간이 쟁점입니다

같은 결제·주문 요청이 네트워크 재시도로 두 번 도착하면 중복 처리가 일어납니다. 멱등성 키는 이것을 막기 위해 클라이언트가 요청마다 만들어 보내는 식별자입니다. 서버가 키를 만들면 재시도 때 같은 키를 보낼 수 없어 의미가 없습니다. 요청 수·보관 기간·키 형식을 넣으면 저장할 키 수와 충돌 확률, 필요한 저장 용량을 계산합니다.

키는 보통 엔드포인트와 키를 합친 범위로 저장하고, 같은 키가 다시 오면 처리를 반복하지 않고 저장해 둔 응답을 그대로 돌려줍니다. 첫 요청이 아직 처리 중일 때 같은 키가 또 오면 잠금이나 유니크 제약으로 한쪽만 통과시켜야 합니다. 멱등성 키를 HTTP 헤더로 표준화하려는 논의가 진행 중이지만 아직 확정된 규격은 아니므로, 헤더 이름과 동작은 API 문서에 직접 적어 두어야 합니다. 2026년 10월 기준입니다.

공인된 권장 키 길이나 보관 기간은 없습니다. 이 페이지는 권장값을 제시하지 않고 입력한 형식의 결과만 계산합니다. 충돌 확률은 키가 고른 난수라는 가정의 근사이며, 실제 키 생성기의 편향은 반영하지 않습니다. 키 저장소 선택이나 실제 중복 요청 판정 구현은 지원하지 않습니다.

자주 묻는 질문

같은 키로 본문이 다른 요청이 오면 어떻게 할까?

처리하지 않고 409 로 거절하는 방식이 널리 쓰입니다. 키가 같으면 같은 요청이라고 약속한 것이므로, 본문이 다르면 클라이언트 쪽 키 재사용 실수일 가능성이 높습니다.

키는 서버가 만들어도 될까?

서버가 만들면 재시도 때 클라이언트가 같은 키를 보낼 수 없어 중복을 막지 못합니다. 키는 클라이언트가 요청 1건마다 만들어 재시도에서도 같은 값을 보내야 합니다.

키를 얼마나 보관해야 할까?

공인된 권장 기간은 없습니다. 클라이언트가 재시도를 포기하는 시점보다 길게 잡는 것이 기준이며, 보관 기간을 넣으면 그 기간의 키 수와 저장 용량을 계산해 줍니다.

🗝️API 멱등성 키 설계 가이드

관련된 도구

요청 타임아웃 단계별 배분 계산기

지수 백오프 재시도 지연 계산기

멱등성 키는 길이보다 범위와 보관 기간이 쟁점입니다

자주 묻는 질문

관련된 도구

요청 타임아웃 단계별 배분 계산기

지수 백오프 재시도 지연 계산기

멱등성 키는 길이보다 범위와 보관 기간이 쟁점입니다

자주 묻는 질문

같은 카테고리 도구