네트워크는 가장 나쁜 지점에서 끊깁니다. 서버는 이미 작업을 했는데 응답은 아직 받지 못한 시점입니다. 멱등성 키가 있으면 이때의 재시도가 안전해집니다.
작동 방식
클라이언트는 의도한 작업 하나마다 고유한 키를 만들어 요청과 함께 보냅니다. 서버는 키를 결과와 함께 저장합니다. 같은 키가 다시 오면 서버는 작업을 다시 하지 않고 저장해 둔 결과를 그대로 돌려줍니다.
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가 왜 더 나빠지는지는 속도 제한을 참고하세요.