등록은 왜 실패했나요?
등록·검증·식별이 실패하는 모든 위치, 실패 사유를 어디서 보는지, 다음에 할 일.
실패는 언제 일어났느냐에 따라 세 곳 중 하나에 나타납니다. 먼저 내 경우를 찾으세요.
| 어디서 봤나 | 의미 | 사유 확인 | 바로가기 |
|---|---|---|---|
API 호출 시 HTTP 4xx/5xx와 errors[].code(PETNOWB2B…) | 작업이 시작되기 전에 요청이 거부됨 | 가능(코드) | 1. 요청 거부 |
작업이 status: FAILED(폴링 또는 *.failed 웹훅) | 작업은 시작했지만 결과를 만들지 못함 | 사유 필드 없음 | 2. 작업 FAILED |
리다이렉트의 petify_status=failed 또는 호스티드 세션 status: FAILED | Web Integration 세션 실패 | 세션에서 가능(errorCode), 리다이렉트는 제한적 | 3. Web Integration 세션 실패 |
실패가 아닌 경우: 검증 불일치(isVerified: false)나 식별 매치 없음(모든 항목 isMatch: false)은 성공한 작업입니다. 결과는 만들어졌고, 단지 일치하지 않은 것입니다.
1. 요청 거부 (HTTP 에러 코드)
응답 본문에 사유가 있습니다.
{ "errors": [{ "code": "PETNOWB2B20015" }] }등록 시 자주 나오는 코드:
| 코드 | HTTP | 원인 | 할 일 |
|---|---|---|---|
PETNOWB2B10000 | 401 | API Key가 잘못되었거나 비활성 | 콘솔에서 키 확인 |
PETNOWB2B10005 | 402 | 결제 필요(펫 한도·결제수단 없음) | 콘솔에서 결제수단 등록 |
PETNOWB2B20007 | 400 | 해당 펫에 진행 중인 등록 작업이 있음 | 그 작업이 끝날 때까지 대기 |
PETNOWB2B20012 | 400 | 촬영 세션이 끝나지 않음 | 업로드를 마친 뒤 제출 |
PETNOWB2B20014 | 400 | 이미 사용한 촬영 세션 | 새 촬영 세션 생성 |
PETNOWB2B20015 | 400 | 종(species) 불일치 | 펫의 종으로 요청 |
PETNOWB2B20018 | 409 | 촬영 세션이 24시간 경과 | 새 촬영 세션 생성 |
PETNOWB2B21001 | 409 | Web Integration: externalPetId가 이미 등록됨 | 다른 ID 사용 또는 기존 펫 삭제 |
PETNOWB2B21003 | 400 | Web Integration: redirectUrl이 허용목록에 없음 | 콘솔에 URL을 먼저 등록 |
전체 코드는 에러 코드를 참고하세요.
2. 작업 FAILED (Server API)
등록(addFingerprints)·검증·식별은 비동기 작업입니다. FAILED 응답에는 status만 있고 에러 코드나 사유 필드가 없습니다. 폴링 응답과 *.failed 웹훅 이벤트 모두 같습니다.
이미지로 결과를 만들 수 없을 때 비동기로 실패하며, 가장 흔한 원인은 이미지 품질 부족입니다.
- 코가 흐리거나 너무 어둡거나 빛 반사로 가려짐
- 살아 있는 동물이 아니라 사진이나 화면을 촬영함(가짜 이미지 검사로 거부)
- 펫의 코가 아닌 이미지
할 일
- 새 촬영 세션을 만들고 SDK 화면 안내에 따라 다시 촬영합니다. 촬영 가이드를 참고하세요.
- 새 세션으로 작업을 다시 제출합니다.
- 등록이 실패하면 지문 없는 펫 프로필(
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_ID | externalPetId가 이미 등록됨 | 다른 ID 사용 또는 콘솔에서 기존 펫 삭제 |
IDENTIFICATION_NOT_IN_PLAN | 플랜에 식별이 없음 | My Page → Billing에서 Plus 선택 |
IDENTIFICATION_PLAN_SELECTION_REQUIRED | 아직 플랜을 고르지 않음 | My Page → Billing에서 플랜 선택 |
errorCode는 열린 목록입니다. 모르는 값은 일반 실패로 처리하세요. Web Integration 세션은 웹훅 이벤트를 보내지 않습니다(결과 받기).