재시도

네트워크가 끊긴 뒤 같은 요청을 다시 보낼 때, 작업이 두 번 실행되지 않게 하는 방법입니다.

작업 제출(POST /v1/jobs)에는 Idempotency-Key 헤더가 필요합니다. 이 키는 "이 요청은 아까 그 요청과 같은 것"이라고 알려 주는 표식입니다.

값은 1~128자 ASCII 문자열이며, 요청마다 겹치지 않는 UUID v4 를 권합니다.

키는 작업 기록과 함께 저장되므로 이름·전화번호·사업자등록번호 같은 고객 정보를 넣지 마세요 — 의미 없는 값이 안전합니다.

같은 키로 다시 보내면

재시도같은 키 · 같은 본문

응답: HTTP 200
작업: 새로 만들지 않고 이미 접수된 작업을 그대로 돌려줍니다
status: 그 작업의 지금 상태입니다. 이미 끝났다면 QUEUED 가 아니라 끝난 상태로 옵니다
일일 한도: 새 작업이 아니므로 한도를 더 쓰지 않습니다

충돌같은 키 · 다른 본문

응답: HTTP 409
코드: IDEMPOTENCY_KEY_CONFLICT
할 일: 먼저 기존 요청의 본문이 실수로 바뀌었는지 확인합니다. 같은 업무의 재전송이면 원래 본문과 키를 그대로 쓰고, 별도의 새 업무로 확정한 경우에만 새 키를 만듭니다

무엇이 같으면 같은 요청인가

비교하는 값	설명
provider	호출할 기관
action	호출할 작업
account_link_id	자동 선택까지 끝난 뒤의 값 — 생략하고 보내도 선택된 자격증명이 같으면 같은 요청입니다
params	작업 파라미터 전체
encrypted_fields	암호화해 보낸 필드 전체

이 다섯 가지가 모두 같으면 같은 요청입니다. 호출 시각이나 그 밖의 헤더는 보지 않습니다.

같은 요청이라도 재전송은 새 제출과 같은 순서로 한도, 요금제, 환경 검사를 먼저 거칩니다. 그래서 데모의 일일 한도를 다 쓴 뒤에는 이미 접수된 작업을 같은 키로 다시 보내도 200 이 아니라 429 POLICY_QUOTA_EXCEEDED 가 옵니다. 그때는 GET /v1/jobs/{job_id} 로 작업 상태를 확인합니다 — 조회는 제출 한도를 쓰지 않습니다.

오류

코드	HTTP	언제
IDEMPOTENCY_KEY_REQUIRED	400	Idempotency-Key 헤더를 넣지 않았습니다.
IDEMPOTENCY_KEY_CONFLICT	409	같은 키를 이미 다른 내용의 요청에 썼습니다.

키를 쓰는 원칙

요청 하나에 키 하나를 만듭니다. 응답을 받지 못해 다시 보낼 때는 같은 키를 그대로 씁니다 — 그래야 서버가 같은 요청임을 알아보고 두 번 실행하지 않습니다.

반대로 새로 실행하려는 요청에는 새 키를 씁니다. 예전 키를 다시 쓰면 그때 만든 작업이 돌아옵니다.

발행·신고·신청처럼 되돌릴 수 없는 작업일수록 재시도에 같은 키를 쓰는 것이 중요합니다. 새 키로 다시 보내면 기관에서 두 번 처리될 수 있습니다. 이미 PROVIDER_OUTCOME_UNCONFIRMED 로 끝난 작업은 키와 상관없이 다시 보내지 말고 기관 화면에서 결과를 먼저 확인합니다 — 작업 처리 흐름.

키는 조직과 환경 단위로 기억됩니다. 같은 조직의 다른 API 키로 호출해도 같은 환경에서 키 값이 같으면 같은 요청으로 봅니다. 환경이 다르면 같은 키도 다른 요청입니다 — 샌드박스에서 쓴 키를 데모나 정식에서 다시 써도 새 작업이 만들어지고, 이전 환경의 작업은 그대로 남습니다.