레퍼런스

오류 코드

실패 응답의 HTTP 상태와 code 값, 뜻과 대처 방법을 정리했습니다. 분기는 항상 code 로 하세요.

실패 응답 형식 #

실패하면 success: false 와 함께 code(고정된 영문 값), error(한국어 설명), 필요하면 meta(추가 정보)가 옵니다. error 문구는 바뀔 수 있으므로 화면 표시·로그용으로만 쓰고, 프로그램 분기는 code 로 하세요.

실패 응답 예시

{
  "success": false,
  "code": "WRONG_PASSWORD",
  "error": "양도 비밀번호가 맞지 않습니다. 4번 더 틀리면 60분 동안 잠깁니다.",
  "meta": { "status": "available", "attemptsLeft": 4 }
}

코드 목록 #

상태 · code	의미 · 대처
400 `BAD_REQUEST`	요청 본문을 JSON으로 읽을 수 없음 Content-Type: application/json 과 본문 형식을 확인합니다.
401 `UNAUTHORIZED`	Authorization 헤더가 없거나 형식이 틀림, 또는 없는·폐기된 API 키 키 값과 Bearer 접두어를 확인하고, 폐기된 키면 새 키로 바꿉니다.
401 `WRONG_PASSWORD`	양도 코드 접수 때 보낸 양도 비밀번호가 틀림. meta.attemptsLeft(남은 횟수), meta.status 판매자에게 비밀번호를 다시 확인합니다. 같은 값으로 재시도하지 않습니다. UNAUTHORIZED 와 상태 코드가 같으니 반드시 code 로 구분하세요.
403 `FORBIDDEN`	업체 이용 중지, 또는 운영 키로 테스트 전용 API(테스트 양도 코드 발급·승인 시뮬레이션) 호출 이용 중지는 핀락에 문의합니다. 테스트 전용 API는 테스트 키로 호출합니다.
404 `NOT_FOUND`	없는 양도 코드, 다른 모드(테스트·운영)의 코드, 이 업체가 접수하지 않았거나 선점이 풀린(해제·승인 기한 만료·판매자 거절·7일 자동 해제) transferId, 판매 중이 아닌 상품 코드와 키 모드가 맞는지 확인합니다. 선점이 풀린 양도 건이면 거래를 멈추고 판매자·구매자에게 알립니다.
409 `ALREADY_CLAIMED`	양도 코드가 이미 다른 곳에 접수(선점)됨. 동시에 접수했을 때 늦은 쪽도 이 오류를 받습니다. meta.status 매물 등록을 막습니다. 같은 업체에서 동시에 보냈을 수 있으면 코드 확인으로 claimed_by_you·pending_approval 인지 확인합니다.
409 `ALREADY_DELIVERED`	양도 코드의 PIN 전달이 이미 끝남 (접수·링크 생성) 접수하지 않습니다. 링크를 만들던 중이면 조회해 delivered 로 처리합니다.
409 `PAYMENT_PENDING`	판매자의 핀락 입금이 아직 확인되지 않아 양도 코드를 접수할 수 없음. meta.status: waiting_payment 판매자에게 입금 확인 뒤 다시 등록하라고 안내합니다.
409 `PASSWORD_NOT_SET`	판매자가 아직 양도 비밀번호를 정하지 않아 접수할 수 없음 판매자에게 핀락 주문 화면에서 양도 비밀번호(숫자 6자리)를 정해 달라고 안내합니다. 코드 확인의 passwordSet 으로 미리 알 수 있습니다.
409 `APPROVAL_PENDING`	판매자가 아직 접수를 승인하지 않아 PIN 전달 링크를 만들 수 없음. meta.approvalExpiresAt(승인 기한) 판매자에게 핀락에서 승인해 달라고 안내하고, 조회로 claimed_by_you 가 된 뒤 링크를 만듭니다.
409 `UNAVAILABLE`	판매자 주문이 취소·환불·환불 심사·실패 등이라 접수할 수 없음, 또는 접수하는 사이 코드 상태가 바뀜 코드를 다시 확인합니다. claimable 이 false 면 접수하지 않습니다.
409 `CONFLICT`	선점 기간(7일)이 지났거나 선점 중이 아닌 양도의 링크 생성, 이미 전달된 양도 해제, 승인 대기가 아닌 테스트 건 승인, 동시 처리 충돌 양도를 다시 조회해 현재 상태를 확인한 뒤 처리합니다.
422 `VALIDATION_ERROR`	요청 형식 오류(meta.issues): 양도 코드 형식(PLX-XXXX-XXXX-XXXX), password 숫자 6자리 아님, externalRef 64자 초과, sharePassword 6~20자 아님, transferId 형식, 테스트 발급의 같은 상품 중복·판매 중이 아닌 상품 요청을 고칩니다. 같은 요청을 그대로 재시도하지 않습니다.
422 `LIMIT_EXCEEDED`	테스트 양도 코드 발급에서 상품별 최대 수량(maxQuantity) 초과 수량을 줄입니다.
423 `LOCKED`	양도 비밀번호를 5번 틀려 그 코드는 60분 동안 접수할 수 없음. meta.status 60분 뒤 판매자에게 비밀번호를 다시 확인해 시도합니다. 직접 틀린 게 아니라면 코드 유출을 의심합니다.
429 `LIMIT_EXCEEDED`	API 키별 호출 한도 초과 (현재 키당 1분에 300회). 양도 코드 대량 대입 조회를 막기 위한 제한입니다. 잠시 기다린 뒤 간격을 늘려 다시 보냅니다. 폴링 간격(30~60초)과 동시 요청 수를 점검합니다.
500 `INTERNAL_ERROR`	핀락 서버 오류. error 문구에 요청 ID가 들어 있습니다. 잠시 뒤 다시 시도하고, 계속되면 요청 ID와 함께 핀락에 문의합니다.

재시도해도 되는 오류 #

네트워크 오류 · 타임아웃 · 5xx: 같은 요청을 다시 보내도 됩니다. 양도 접수는 이미 이 업체가 접수한 코드면 같은 양도 객체를 돌려주므로, 응답을 받지 못했다면 같은 코드로 다시 호출하세요. 링크 생성을 다시 부르면 이전 링크가 폐기되니, 재시도 전에 조회로 share 를 확인하세요.
400 · 401 · 403 · 404 · 422: 요청이나 설정을 고쳐야 합니다. 그대로 재시도해도 같은 결과입니다.
401 WRONG_PASSWORD · 423 LOCKED: 판매자에게 비밀번호를 다시 확인하기 전에는 재시도하지 마세요. 틀릴 때마다 판매자에게 알림이 갑니다.
409: 상황을 확인한 뒤 처리합니다. 코드 확인이나 양도 조회로 현재 상태를 보고, 상태별 대응은 양도 코드 상태를 참고하세요.
429 LIMIT_EXCEEDED: 짧은 간격으로 반복하지 말고, 잠시 기다린 뒤 간격을 늘려 다시 보내세요.

문의할 때

응답 헤더의 X-Request-Id 와 요청 시각, transferId(또는 코드 끝 4자리)를 함께 알려 주시면 빠르게 확인할 수 있습니다.