중복 처리 없이 안전하게 재시도하기

요청을 보냈지만 응답을 받지 못했다면, 같은 요청을 다시 보내야 할 수 있습니다. 이때 재시도 식별값을 함께 보내면 서버가 이미 처리한 요청인지 확인합니다.

같은 식별값과 같은 내용으로 다시 요청하면 중복 발급이나 중복 적립 없이 처음 처리한 결과를 돌려줍니다.

사용 방법

새 작업마다 고유한 재시도 식별값을 만들어 Idempotency-Key 헤더에 넣으세요. 응답을 받지 못해 같은 작업을 재시도할 때만 같은 값을 사용합니다.

Request
curl -X POST "https://api.vivoldi.com/api/coupon/v1/create" \
  -H "Authorization: APIKEY {YOUR_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-20260920-000412" \
  -d '{
    "nm": "$5 discount coupon",
    "discTypeIdx": 458,
    "disc": 5
  }'

헤더를 보내기 어렵다면 요청 본문의 requestId 필드에 같은 값을 넣을 수 있습니다. 헤더와 본문을 모두 보내는 경우 두 값이 같아야 합니다.

필드 설명 유형
Idempotency-Key HTTP 헤더. 영문 대소문자, 숫자, . _ : -로 구성된 8~64자입니다. 새 작업마다 다른 값을 사용하세요. string
requestId 요청 본문 필드. 헤더 대신 사용할 수 있으며 형식은 같습니다. string

적용 범위

쿠폰 생성·사용, 스탬프 생성·적립·차감·혜택 사용에 적용됩니다. v2 쿠폰·스탬프 수정 API도 재시도 식별값을 지원합니다.

식별값은 선택 항목입니다. 보내지 않으면 기존 방식으로 처리됩니다. 기록은 72시간 보관하며, 이후 같은 값으로 요청하면 새 작업으로 처리될 수 있습니다.

식별값은 조직과 작업 종류별로 구분됩니다. 한 조직에서 서로 다른 작업에 같은 값을 재사용하지 마세요.

응답과 오류 대응

이미 성공한 요청을 같은 식별값과 같은 내용으로 재시도하면 처음 처리한 결과를 돌려줍니다. 작업과 Webhook은 다시 실행하지 않습니다.

충돌 오류는 HTTP 409이며 응답 본문의 code도 409입니다. 원인은 message를 확인하세요. HTTP 200이어도 code가 0인지 확인해야 합니다.

상황 HTTP code 대응
같은 식별값·같은 내용으로 재시도 2000 처음 결과가 반환됩니다. 추가 처리는 필요하지 않습니다.
같은 식별값을 다른 내용에 사용 409409 새 작업에는 새 식별값을 사용하세요.
같은 식별값의 앞선 요청이 처리 중 409409 잠시 후 같은 식별값으로 다시 요청하세요.
헤더와 requestId 값이 다름 4001213 두 값을 같게 맞추거나 하나만 보내세요.
식별값 형식이 올바르지 않음 4001216 영문 대소문자, 숫자, . _ : -로 구성된 8~64자로 고치세요.
다른 요청이 같은 대상을 먼저 수정 409409 최신 상태를 확인한 뒤 요청 내용을 다시 검토하세요.

안전하게 사용하는 방법

  • 주문번호처럼 같은 작업의 재시도에서 다시 사용할 수 있는 값을 선택하세요. 매번 새 값을 만들면 앞선 요청과 연결되지 않습니다.
  • 응답을 받지 못했다면 같은 식별값과 같은 요청 내용으로 재시도하세요. 내용을 바꿨다면 새 식별값을 사용하세요.
  • HTTP 409는 원인에 따라 대응이 다릅니다. 처리 중이면 잠시 후 재시도하고, 식별값 재사용이나 동시 수정이면 요청 내용을 확인하세요.