Petnow LogoPetnow

등록은 왜 실패했나요?

등록·검증·식별이 실패하는 모든 위치, 실패 사유를 어디서 보는지, 다음에 할 일.

실패는 언제 일어났느냐에 따라 세 곳 중 하나에 나타납니다. 먼저 내 경우를 찾으세요.

어디서 봤나의미사유 확인바로가기
API 호출 시 HTTP 4xx/5xx와 errors[].code(PETNOWB2B…)작업이 시작되기 전에 요청이 거부됨가능(코드)1. 요청 거부
작업이 status: FAILED(폴링 또는 *.failed 웹훅)작업은 시작했지만 결과를 만들지 못함사유 필드 없음2. 작업 FAILED
리다이렉트의 petify_status=failed 또는 호스티드 세션 status: FAILEDWeb Integration 세션 실패세션에서 가능(errorCode), 리다이렉트는 제한적3. Web Integration 세션 실패

실패가 아닌 경우: 검증 불일치(isVerified: false)나 식별 매치 없음(모든 항목 isMatch: false)은 성공한 작업입니다. 결과는 만들어졌고, 단지 일치하지 않은 것입니다.

1. 요청 거부 (HTTP 에러 코드)

응답 본문에 사유가 있습니다.

{ "errors": [{ "code": "PETNOWB2B20015" }] }

등록 시 자주 나오는 코드:

코드HTTP원인할 일
PETNOWB2B10000401API Key가 잘못되었거나 비활성콘솔에서 키 확인
PETNOWB2B10005402결제 필요(펫 한도·결제수단 없음)콘솔에서 결제수단 등록
PETNOWB2B20007400해당 펫에 진행 중인 등록 작업이 있음그 작업이 끝날 때까지 대기
PETNOWB2B20012400촬영 세션이 끝나지 않음업로드를 마친 뒤 제출
PETNOWB2B20014400이미 사용한 촬영 세션새 촬영 세션 생성
PETNOWB2B20015400종(species) 불일치펫의 종으로 요청
PETNOWB2B20018409촬영 세션이 24시간 경과새 촬영 세션 생성
PETNOWB2B21001409Web Integration: externalPetId가 이미 등록됨다른 ID 사용 또는 기존 펫 삭제
PETNOWB2B21003400Web Integration: redirectUrl이 허용목록에 없음콘솔에 URL을 먼저 등록

전체 코드는 에러 코드를 참고하세요.

2. 작업 FAILED (Server API)

등록(addFingerprints)·검증·식별은 비동기 작업입니다. FAILED 응답에는 status만 있고 에러 코드나 사유 필드가 없습니다. 폴링 응답과 *.failed 웹훅 이벤트 모두 같습니다.

이미지로 결과를 만들 수 없을 때 비동기로 실패하며, 가장 흔한 원인은 이미지 품질 부족입니다.

  • 코가 흐리거나 너무 어둡거나 빛 반사로 가려짐
  • 살아 있는 동물이 아니라 사진이나 화면을 촬영함(가짜 이미지 검사로 거부)
  • 펫의 코가 아닌 이미지

할 일

  1. 새 촬영 세션을 만들고 SDK 화면 안내에 따라 다시 촬영합니다. 촬영 가이드를 참고하세요.
  2. 새 세션으로 작업을 다시 제출합니다.
  3. 등록이 실패하면 지문 없는 펫 프로필(hasFingerprint: false)이 남을 수 있습니다. 이 프로필도 과금에 포함되므로 삭제하거나 같은 펫으로 다시 시도하세요. 미완료 레코드 정리를 참고하세요.

좋은 이미지로도 같은 펫이 계속 실패하면 jobId와 함께 support@petnow.io로 문의하세요.

3. Web Integration 세션 실패

리다이렉트에서는 완료 페이지가 petify_status=failed를 받습니다. petify_code는 한 가지 사유, FEATURE_UNAVAILABLE(계정 플랜에서 식별 사용 불가)일 때만 붙습니다. 촬영 품질 등 다른 실패에는 코드가 없습니다. 완료 리다이렉트 파라미터를 참고하세요.

서버에서는 GET /v2/hosted-sessions/{id}(레퍼런스)로 세션을 읽습니다. 실패한 세션은 status: FAILED와 errorCode를 가집니다.

errorCode의미할 일
CAPTURE_FAILED촬영 또는 품질 검사에서 결과를 만들지 못함사용자에게 새 링크·세션 제공
DUPLICATE_EXTERNAL_PET_IDexternalPetId가 이미 등록됨다른 ID 사용 또는 콘솔에서 기존 펫 삭제
IDENTIFICATION_NOT_IN_PLAN플랜에 식별이 없음My Page → Billing에서 Plus 선택
IDENTIFICATION_PLAN_SELECTION_REQUIRED아직 플랜을 고르지 않음My Page → Billing에서 플랜 선택

errorCode는 열린 목록입니다. 모르는 값은 일반 실패로 처리하세요. Web Integration 세션은 웹훅 이벤트를 보내지 않습니다(결과 받기).

관련 문서

On this page