---
title: "멱등성 키(Idempotency Key)란? 안전한 API 재시도 | BroadRouter"
description: "멱등성 키는 클라이언트가 만들어 요청에 붙이는 고유 ID로, 재시도해도 이중 결제 같은 효과가 반복되지 않게 합니다. 작동 방식과 IETF 헤더를 정리했습니다."
url: https://broadrouter.com/ko/glossary/idempotency-key/
lang: ko
updated: 2026-11-14
publisher: BroadRouter (a BroadNet site); API by BroadNet Inference, https://inference.broadnet.ai
---

이 페이지는 영어 원문을 AI의 도움을 받아 번역했습니다. [영어 원문 읽기](https://broadrouter.com/glossary/idempotency-key/) (2026-11-14 업데이트).

# 멱등성 키(idempotency key)

업데이트 2026-11-14

멱등성 키(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는 멱등성을 제공하지 않는 한 재시도해도 안전하지 않습니다)

## 왜 중요한가

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

## BroadNet Inference에서는

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

```bash
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)에 대해서는 멱등성 키를 문서화하지 않습니다. 그쪽에서 무엇을 재시도할지는 [오류 코드와 재시도](https://broadrouter.com/ko/guides/errors-and-retries/)를, 무작정 재시도하면 429가 왜 더 나빠지는지는 [속도 제한](https://broadrouter.com/ko/glossary/rate-limit/)을 참고하세요.

## 자주 묻는 질문

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

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

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

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

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

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

## 함께 보기

-   [지수 백오프(exponential backoff)](https://broadrouter.com/ko/glossary/exponential-backoff/) (용어)
-   [속도 제한(rate limit)](https://broadrouter.com/ko/glossary/rate-limit/) (용어)
-   [API 키(API key)](https://broadrouter.com/ko/glossary/api-key/) (용어)
-   [동시 처리(concurrency)](https://broadrouter.com/ko/glossary/concurrency/) (용어)
-   [BroadNet Inference 오류 코드와 재시도해야 하는 경우](https://broadrouter.com/ko/guides/errors-and-retries/) (가이드)
-   [IP 허용 목록으로 API 키를 내 서버에만 묶기](https://broadrouter.com/ko/guides/api-keys-ip-allow-lists/) (가이드)
-   [장시간 실행 에이전트: 버티는 타임아웃, 재시도, 체크포인트](https://broadrouter.com/ko/blog/long-running-agents-timeouts-retries/) (글)
-   [시간제 LLM API 키: 시간당 정액 요금 완벽 정리](https://broadrouter.com/ko/blog/hourly-llm-api-key-explained/) (글)

실제 워크로드로 테스트해 보세요. 신규 계정에는 US$5 상당의 초기 크레딧이 제공되며 Gemma 및 음성 전사에 사용할 수 있습니다. DeepSeek, GLM 및 Qwen3.8 모델은 충전이 필요합니다.

[시작하기](https://inference.broadnet.ai/account/?utm_source=broadrouter&utm_medium=referral&utm_campaign=ko-glossary-idempotency-key&utm_content=page-cta) ·

**출처**

-   [IETF HTTPAPI, The Idempotency-Key HTTP Header Field(인터넷 초안)](https://datatracker.ietf.org/doc/draft-ietf-httpapi-idempotency-key-header/)
-   [AWS Builders' Library, 타임아웃, 재시도, 지터를 더한 백오프(멱등성 토큰)](https://builder.aws.com/content/3EumjoZascWd1oZiEgL8ORlv3qE/timeouts-retries-and-backoff-with-jitter)
-   [BroadNet Inference API 레퍼런스, 시간제 키(request\_id 멱등성) (영어)](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=ko-glossary-idempotency-key&utm_content=sources#hourly-keys)
