BroadRouter
시작하기

멱등성 키(idempotency key)

업데이트

멱등성 키(idempotency key)는 결제나 구매처럼 상태를 바꾸는 요청에 클라이언트가 붙이는 고유한 값으로, 보통 UUID 같은 무작위 ID입니다. 같은 요청이 같은 키로 다시 오면 서버는 작업을 두 번 수행하지 않고 처음 결과를 돌려줍니다.

다른 이름: 멱등키, 멱등성, 멱등 요청, 멱등한 재시도, 중복 결제 방지, Idempotency-Key header, idempotency key, idempotency token, idempotent request, idempotent retry

네트워크는 가장 나쁜 지점에서 끊깁니다. 서버는 이미 작업을 했는데 응답은 아직 받지 못한 시점입니다. 멱등성 키가 있으면 이때의 재시도가 안전해집니다.

작동 방식

클라이언트는 의도한 작업 하나마다 고유한 키를 만들어 요청과 함께 보냅니다. 서버는 키를 결과와 함께 저장합니다. 같은 키가 다시 오면 서버는 작업을 다시 하지 않고 저장해 둔 결과를 그대로 돌려줍니다.

IETF HTTPAPI 워킹 그룹은 이를 Idempotency-Key 요청 헤더로 표준화하고 있습니다(2026년 10월 초안 08, 아직 RFC 아님). 초안은 키를 “a unique value generated by the client which the resource uses to recognize subsequent retries of the same request”(번역: 리소스가 같은 요청의 이후 재시도를 알아보는 데 쓰는, 클라이언트가 생성한 고유한 값)라고 설명하고, UUID나 그와 비슷한 무작위 ID를 권장합니다. 초안이 정한 오류 상황은 다음과 같습니다.

상황 상태 코드
필요한 곳에 키가 없음 400 Bad Request
원래 요청이 아직 처리 중 409 Conflict
다른 본문으로 키를 재사용 422 Unprocessable Content

AWS Builders’ Library도 클라이언트 쪽에서 같은 점을 짚습니다. “APIs with side effects aren’t safe to retry unless they provide idempotency.”(번역: 부작용이 있는 API는 멱등성을 제공하지 않는 한 재시도해도 안전하지 않습니다)

왜 중요한가

지수 백오프를 쓴 재시도는 표준적인 관행이고, 많은 SDK가 자동으로 재시도합니다. 멱등성이 없으면 타임아웃 뒤의 재시도로 주문이나 결제가 두 번 생길 수 있습니다. 키가 있으면 첫 시도가 어떻게 끝났든 재시도해도 안전합니다. 그래서 사람이 지켜보지 않는 상태에서 무언가를 구매하거나 예약하거나 생성하는 에이전트와 스크립트에 꼭 필요한 도구입니다.

BroadNet Inference에서는

BroadNet은 시간제 키 구매에 이 패턴을 씁니다. POST /portal/keys/hourly는 JSON 본문에서 request_id를 받으며, 문서에는 “Idempotency is required for money safety”(번역: 금전적 안전을 위해 멱등성이 필요합니다)라고 적혀 있습니다.

curl -X POST https://inference.broadnet.ai/portal/keys/hourly \
  -H "Authorization: Bearer <portal-credential>" \
  -H "Content-Type: application/json" \
  -d '{"request_id":"order-20260920-001","label":"kiosk-1"}'

request_id를 재사용해도 키가 추가로 생성되거나 청구되지 않습니다. 타임아웃, 연결 끊김, 409 mint_in_progress, 5xx 오류가 나면 같은 request_id로 재시도하세요. 재전송된 요청에는 already_issued: true와 키의 별칭이 반환되며, 원본 키는 처음 성공한 응답에만 들어 있습니다. 문서는 이렇게 말합니다. “Never generate a replacement id until the original result is known.”(번역: 원래 결과를 알기 전에는 절대 대체 id를 만들지 마세요)

BroadNet은 /v1/chat/completions나 전사(transcription)에 대해서는 멱등성 키를 문서화하지 않습니다. 그쪽에서 무엇을 재시도할지는 오류 코드와 재시도를, 무작정 재시도하면 429가 왜 더 나빠지는지는 속도 제한을 참고하세요.

자주 묻는 질문

멱등성 키는 언제 새로 만들어야 하나요?

의도한 작업이 새로 생길 때만 만드세요. 한 작업을 재시도할 때는 매번 같은 키를 쓰고, 첫 시도의 결과를 알기 전에는 새 키를 만들지 마세요.

LLM 채팅 완성 요청에도 멱등성 키가 필요한가요?

텍스트 생성에는 지속되는 부작용이 없으므로, 채팅 요청이 반복되면 보통 토큰 비용이 한 번 더 들 뿐입니다. 키가 중요한 것은 돈이 청구되거나 리소스가 생성되는 호출입니다. BroadNet은 채팅 완성이 아니라 시간제 키 구매에 대해서만 이를 문서화합니다.

같은 키를 다른 요청 본문과 함께 다시 쓰면 어떻게 되나요?

IETF 초안은 키가 이미 다른 요청에 묶여 있으므로 서버가 422 Unprocessable Content로 거부해야 한다고 말합니다.

Markdown으로 읽기ChatGPT에 질문하기Claude에 질문하기Perplexity에 질문하기