멱등성과 중복 요청 방지

모든 생성 API가 자체적으로 멱등한 것은 아닙니다. 변경 요청을 보내기 전에 업무 식별자와 결과 복구 방법을 정합니다.

계정

POST /accounts는 같은 uid에 추가 계정을 만들 수 있습니다. /users/{uid}/accounts를 먼저 조회하고 고객사 백엔드에서 동시 생성을 직렬화하며 선택한 account_id를 트랜잭션으로 저장합니다.

내부이체와 외부 출금

전역에서 고유한 client_request_id를 사용하고 요청 전에 주문 또는 지급 건과 연결해 저장합니다.

응답이 유실되면:

1. 기존 client_request_id를 유지합니다.
2. GET /withdrawals/client-request/{client_request_id}를 호출합니다.
3. 반환된 withdrawal_id를 저장하고 상태 조회를 계속합니다.
4. 원본 결과가 없음을 확인하고 고객사 정책을 적용한 뒤에만 새 요청을 만듭니다.

WITHDRAWAL_NOT_FOUND는 조회 시점에 레코드를 찾지 못했다는 뜻입니다. 원본 요청이 아직 처리 중일 수 있으므로 단 한 번의 404를 미처리 확정으로 사용하지 않습니다. 기존 ID로 제한된 간격과 횟수의 복구 조회를 수행합니다. 미확정 상태가 지속되면 변경 요청을 중단하고 request_id와 업무 식별자로 지원 채널에 확인합니다. 중복 또는 충돌 오류도 새 ID로 우회하지 않고 원본 요청과 저장된 자금 이동 의도를 먼저 대조합니다.

Timeout이나 HTTP 500만으로 변경 요청을 자동 재시도하지 않습니다. 읽기 요청은 error.action이 RETRY_LATER일 때 새 HMAC 헤더와 제한된 지수 backoff로 재시도할 수 있습니다.

권장 고객사 레코드

업무 유형과 ID, client_request_id, 요청 fingerprint, OOLIN 리소스 ID, 상태, 최초 시도 시각, 마지막 확인 시각, 최종 결과를 저장합니다. 업무 요청과 request ID에 unique constraint를 적용합니다.

같은 업무 ID가 다른 금액·자산·출금 계정·목적지로 들어오면 충돌로 거절합니다. 하나의 client request ID는 변경되지 않는 금융 의도 하나를 나타냅니다.

계정 생성에는 client_request_id가 없으므로 고객 식별자에 lock을 적용하고 기존 계정을 조회한 뒤 없을 때만 생성하며 mapping을 commit한 후 lock을 해제합니다.