개발자 문서
개발자 문서

재시도

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

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

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

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

MCP 의 tools/call 에는 이 헤더가 없습니다.

같은 키로 다시 보내면

재시도같은 키 · 같은 본문
응답
HTTP 200
작업
새로 만들지 않고 이미 접수된 작업을 그대로 돌려줍니다
status
그 작업의 지금 상태입니다. 이미 끝났다면 QUEUED 가 아니라 끝난 상태로 옵니다
한도
새 작업이 아니므로 한도를 더 쓰지 않고, 한도를 다 쓴 뒤에도 같은 키와 같은 본문이면 200 으로 돌아옵니다
충돌같은 키 · 다른 본문
응답
HTTP 409
코드
IDEMPOTENCY_KEY_CONFLICT
할 일
먼저 기존 요청의 본문이 실수로 바뀌었는지 확인합니다. 같은 업무의 재전송이면 원래 본문과 키를 그대로 쓰고, 별도의 새 업무로 확정한 경우에만 새 키를 만듭니다
같은 키에 같은 본문이면 기존 작업을 그대로 돌려주고, 같은 키에 다른 본문이면 409 로 막습니다.

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

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

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

재전송도 인증, 환경, 요금제 검사와 분당 요청 수 한도는 새 제출과 똑같이 받습니다.

  • 그래서 데모의 일일 한도나 체험 총량을 다 쓴 뒤에도 이미 접수된 작업을 같은 키와 같은 본문으로 다시 보내면 429 가 아니라 200 으로 그 작업이 돌아옵니다.
  • 작업의 지금 상태만 보려면 GET /v1/jobs/{job_id} 를 씁니다. 조회는 사용 토큰(하루, 한 달, 데모 총량)을 쓰지 않지만, 분당 요청 수 한도는 제출과 함께 셉니다.

확인값을 받는 쓰기 작업의 재시도

기관에 쓰기를 하는 작업 중 일부는 제출 전에 사용자의 확인을 받습니다.

다시 보내는 규칙은 다른 작업과 같습니다. 같은 키로 이미 접수된 작업이 있으면 서버는 확인값을 보기 전에 그 작업을 돌려줍니다.

  • 확인값을 넣어 보낸 요청의 응답을 받지 못했다면 같은 키, 같은 본문, 같은 확인값으로 그대로 다시 보냅니다.
  • 확인값 없이 같은 키와 같은 본문으로 보내도 이미 접수된 작업이면 새 확인값을 주지 않고 200 으로 그 작업이 돌아옵니다.
  • 접수되지 않은 키에서 확인값이 만료됐거나, 이미 다른 요청에 썼거나, 확인한 본문과 달라졌다면 409 WRITE_CONFIRMATION_INVALID 입니다.
  • 접수된 키에 본문이 달라진 요청을 보내면 확인값과 상관없이 409 IDEMPOTENCY_KEY_CONFLICT 입니다.
  • 확인값을 넣는 칸은 멱등 판정에서 빠집니다. 확인값만 달라도 같은 요청입니다.

오류

코드HTTP언제
IDEMPOTENCY_KEY_REQUIRED400Idempotency-Key 헤더를 넣지 않았습니다.
IDEMPOTENCY_KEY_CONFLICT409같은 키를 이미 다른 내용의 요청에 썼습니다.
WRITE_CONFIRMATION_REQUIRED400확인값이 필요한 쓰기 작업을 params.confirmation_token 없이 처음 보냈습니다. 응답에 새 확인값과 미리보기가 있습니다. 같은 키로 이미 접수된 작업이 있으면 이 오류가 아니라 200 으로 그 작업이 옵니다.
WRITE_CONFIRMATION_INVALID409접수되지 않은 키에서 확인값이 만료됐거나, 이미 다른 요청에 썼거나, 확인한 본문과 달라졌습니다. 확인값 없이 다시 보내면 새 확인값을 받습니다.

키를 쓰는 원칙

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

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

발행, 신고, 신청처럼 되돌릴 수 없는 작업일수록 재시도에 같은 키를 쓰는 것이 중요합니다.

이미 PROVIDER_OUTCOME_UNCONFIRMED 로 끝난 작업은 키와 상관없이 다시 보내지 말고 기관 화면에서 결과를 먼저 확인합니다 — 작업 처리 흐름.

키는 조직과 환경 단위로 기억됩니다.

  • 같은 조직의 다른 API 키로 호출해도 같은 환경에서 키 값이 같으면 같은 요청으로 봅니다.
  • 환경이 다르면 같은 키도 다른 요청입니다. 데모에서 쓴 키를 정식에서 다시 써도 새 작업이 만들어지고, 이전 환경의 작업은 그대로 남습니다.

도구 호출(MCP)의 재시도

MCP 의 tools/call 은 Idempotency-Key 헤더도 JSON-RPC id 도 재시도 판정에 쓰지 않습니다.

응답을 받지 못한 채 같은 요청을 다시 보낼 때 이 키가 같으면, 서버는 작업을 새로 만들지 않고 그 키로 처음 접수된 작업으로 응답합니다.

  • 이 인수를 받는 도구는 tools/list 응답에서 그 도구의 inputSchema.properties 에 request_idempotency_key 가 있습니다. 필수가 아닙니다.
  • 여럿을 묶어 한 번에 실행하는 팩 도구, 기관이나 외부 서비스에 쓰는 도구, 파일을 올리는 도구, 끝난 작업의 결과를 읽는 도구는 이 인수를 받지 않습니다.
  • 인증 정보 없이 부르는 맛보기 호출에는 쓸 수 없습니다.
  • 키를 넣지 않고 다시 부르면 새 요청으로 처리돼 작업이 하나 더 만들어지고 사용 토큰이 다시 듭니다.

쓰는 순서

  1. 키를 만들어 저장합니다

    요청마다 겹치지 않는 값을 만들어 첫 요청을 보내기 전에 저장해 둡니다. 보낸 뒤에 만들면 응답을 받지 못했을 때 같은 키를 쓸 수 없습니다. UUID v4 를 권하고, 고객 정보는 넣지 않습니다.

  2. 요청 인수에 넣어 보냅니다

    다른 인수와 같은 자리에 request_idempotency_key 를 넣습니다.

  3. 응답을 받지 못하면 같은 키로 다시 보냅니다

    도구와 자격증명과 인수가 처음과 같아야 합니다. 이미 접수됐다면 새 작업 없이 그 작업으로 응답하고 사용 토큰도 다시 들지 않습니다. 접수되지 않았다면 이때 새 작업이 만들어집니다.

  4. 새로 실행하려면 새 키를 씁니다

    같은 도구를 일부러 다시 실행하거나 인수를 바꿀 때는 새 키를 만들어 처음부터 합니다. 예전 키를 다시 쓰면 그때 만든 작업이 돌아오고, 인수가 다르면 거절됩니다.

요청 예

json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "<tools/list 에서 받은 이름>",
    "arguments": {
      "<도구 인수 이름>": "<도구 인수 값>",
      "request_idempotency_key": "<요청마다 새로 만든 값>"
    }
  }
}

도구 호출에서 키에 따른 처리

보낸 요청서버의 처리
같은 키, 같은 도구, 같은 자격증명, 같은 인수새 작업을 만들지 않고 처음 접수된 작업으로 응답합니다. 사용 토큰을 다시 쓰지 않고, 한도를 다 쓴 뒤에도 같습니다.
같은 키, 도구나 자격증명이나 인수가 다름-32602 로 거절합니다. error.data.error_code 는 IDEMPOTENCY_KEY_CONFLICT 이고 error.data.safe_to_retry 는 false 입니다. 새 작업은 만들지 않습니다.
새 키새 요청입니다. 새 작업이 만들어지고 사용 토큰이 듭니다. 한도를 다 썼다면 POLICY_QUOTA_EXCEEDED 로 거절됩니다.
키 없음새 요청입니다. 다시 부를 때마다 작업이 하나씩 더 만들어지고 사용 토큰이 듭니다. 같은 내용의 중복 접수를 막는 도구는 이미 접수된 작업을 돌려줄 수 있습니다.

다시 보낸 요청도 받는 검사

다시 보낸 요청도 인증, 요금제, 상품 판매 상태, 자격증명 상태, 약관 동의 검사를 새 호출과 똑같이 받습니다.

account_link_id 를 생략해 서버가 자격증명을 자동으로 고르게 한 호출은, 그 사이 자동으로 고른 자격증명이 바뀌면 인수가 같아도 다른 요청입니다.

키가 거절되는 경우

상황응답
인증 정보 없이 부른 맛보기 호출에 키를 넣음-32602 이고 메시지가 request_idempotency_key 는 인증된 요청에서만 쓸 수 있다고 알립니다. 키를 빼고 부릅니다.
이 인수를 받지 않는 도구에 키를 넣음-32602 이고 메시지가 그 도구는 request_idempotency_key 를 지원하지 않는다고 알립니다. 키를 빼고 그 도구의 안내를 따릅니다.
키 형식이 틀림: 문자열이 아님, 비었거나 공백뿐임, 128자를 넘음, ASCII 가 아님, 제어 문자가 들어 있음-32602 이고 메시지가 공백만으로 이루어지지 않은 1~128자의 표시 가능한 ASCII 문자열이어야 한다고 알립니다. 보낸 값은 메시지에 되풀이하지 않습니다.

세 경우 모두 작업은 만들어지지 않고 error.data.error_code 는 오지 않습니다.

응답을 받지 못한 요청을 새 키로 바꿔 다시 보내면 별도 실행이 됩니다. 처음 요청의 처리 결과를 모르는 동안에는 처음 키를 그대로 씁니다.

request_idempotency_key 와 도구가 자체로 받는 idempotency_key 는 다른 칸입니다.

계좌 여러 개나 모든 계좌를 한 번에 부르는 호출(모든 계좌를 한 번에 호출하기)에도 이 인수를 씁니다.