에러 코드

개요

Petnow API는 에러 발생 시 HTTP 상태 코드와 함께 상세한 에러 정보를 반환합니다.

에러 응답 형식

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

필드	타입	설명
`errors`	array	에러 배열
`errors[].code`	string	에러 코드 (PETNOWB2BXXXXX 형식)

HTTP 상태 코드

상태 코드	설명
`200`	성공
`201`	리소스 생성 성공
`202`	접수됨 — 비동기 작업 시작 (addFingerprints / verify / identify)
`204`	삭제 성공 (응답 본문 없음)
`400`	잘못된 요청
`401`	인증 실패
`402`	결제 필요
`403`	권한 없음
`404`	리소스 없음
`409`	충돌 (Web Integration: 이미 등록된 `externalPetId`)
`410`	만료됨 (Web Integration: 이미 소비된 결과 코드)
`500`	서버 내부 오류
`503`	서비스 일시 중단 (Web Integration: 세션 발급 일시 중단)

인증 관련 에러 (401)

PETNOWB2B10000 - InvalidApiKeyException

상태 코드: 401

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

원인

API Key가 잘못됨
API Key가 누락됨
API Key가 비활성화됨

해결 방법

x-petnow-api-key 헤더 확인
Petify Console에서 발급한 올바른 API Key 사용
Petify Console의 마이페이지 → API Key 관리에서 키 활성 상태를 확인(필요 시 재발급)

PETNOWB2B10001 - ValidationError

상태 코드: 400

이 에러는 요청 파라미터의 유효성 검사 실패 시 발생하며, 다른 에러 코드와 달리 details 필드를 통해 구체적인 검증 오류 정보를 제공합니다.

{
  "errors": [
    {
      "code": "PETNOWB2B10001",
      "details": {
        "petId": ["This field is required."]
      }
    }
  ]
}

원인

필수 파라미터 누락
잘못된 타입 또는 형식의 파라미터 값
허용되지 않는 열거형 값 (예: species에 DOG, CAT 외의 값)

해결 방법

details 필드에서 실패한 필드명과 오류 메시지 확인
요청 파라미터 수정 후 재시도

결제 관련 에러 (402)

PETNOWB2B10005 - PetLimitExceededError

상태 코드: 402

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

원인

데모 플랜의 최대 펫 등록 수를 초과함

해결 방법

Petify Console에서 직접 유료 플랜으로 업그레이드 (마이페이지 → 결제)

PETNOWB2B10011 - IdentificationNotInPlanError

상태 코드: 402

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

원인

현재 플랜에 식별(1:N 매칭)이 포함되어 있지 않음. 식별 권한이 없는 계정(Petify Core)이 POST /v2/pets:identify 또는 action: IDENTIFY로 POST /v2/hosted-sessions를 호출하면 반환됩니다.
향후 릴리즈부터 이 코드가 반환될 수 있습니다. 미리 처리해 두면 전환 시 영향이 없습니다.

해결 방법

Petify Console에서 식별이 포함된 플랜(Petify Plus)으로 업그레이드 (마이페이지 → 결제)

PETNOWB2B10012 - IdentificationPlanSelectionRequiredError

상태 코드: 402

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

원인

레거시 플랜에서 Petify Core / Plus로 이전 중인 계정이 이전 예정일까지 플랜을 선택하지 않아 식별 요청이 차단된 상태. PETNOWB2B10011과 달리 두 플랜 중 어느 것을 선택해도 해제됩니다.
향후 릴리즈부터 이 코드가 반환될 수 있습니다. 미리 처리해 두세요.

해결 방법

Petify Console에서 플랜을 선택하세요 (마이페이지 → 결제). Core 또는 Plus 중 하나를 선택하면 이 상태가 해제되며, 식별 자체를 사용하려면 Plus가 필요합니다.

접근 권한 에러 (403)

PETNOWB2B10010 - Account API access suspended

상태 코드: 403

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

원인

결제수단 문제로 계정의 API 사용이 정지된 상태입니다. API Key 문제가 아니라 계정 단위 상태입니다.

해결 방법

Petify Console에서 결제수단 문제를 해결하세요.

요청 관련 에러 (400)

PETNOWB2B20007 - PetAlreadyHasFingerprintAdditionJobException

상태 코드: 400

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

원인

펫에 이미 진행 중인 지문 추가 작업이 있음

해결 방법

기존 작업 완료 대기
작업 상태 폴링 후 재시도

PETNOWB2B20009 - PetHasNoFingerprintException

상태 코드: 400

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

원인

검증 시 펫에 등록된 지문이 없음

해결 방법

먼저 지문 등록 완료
addFingerprints 엔드포인트로 지문 추가

PETNOWB2B20011 - NoPetIdCaptureSessionException

상태 코드: 400

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

원인

PET_PROFILE_REGISTRATION 또는 PET_VERIFICATION 목적의 세션 생성 시 petId 누락

해결 방법

세션 생성 시 petId 파라미터 포함
PET_IDENTIFICATION은 petId 불필요

PETNOWB2B20012 - CaptureSessionIsNotFinishedException

상태 코드: 400

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

원인

세션에 지문 이미지가 업로드되지 않음
세션에 외관 이미지가 업로드되지 않음 (외관 이미지는 모든 용도에서 필수)

해결 방법

지문 이미지 업로드 (등록은 최소 5장, 검증·식별은 최소 3장)
UI 모듈이 제공하는 외관 이미지 업로드
모든 업로드가 201을 받은 뒤에 작업 시작

PETNOWB2B20013 - InvalidSessionPurposeError

상태 코드: 400

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

원인

캡처 세션의 목적(purpose)이 요청한 작업과 맞지 않음
예: PET_IDENTIFICATION 목적의 세션으로 지문 등록 시도

해결 방법

올바른 목적의 세션 생성
PET_PROFILE_REGISTRATION, PET_VERIFICATION, PET_IDENTIFICATION 중 적합한 purpose 선택

PETNOWB2B20014 - CaptureSessionAlreadyUsedError

상태 코드: 400

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

원인

이미 사용된 캡처 세션을 재사용 시도

해결 방법

새 캡처 세션을 생성한 후 재시도

PETNOWB2B20015 - SpeciesMismatchError

상태 코드: 400

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

원인

캡처 세션의 species와 펫의 species가 다름

해결 방법

펫과 동일한 species로 세션 생성
올바른 펫 ID 확인

PETNOWB2B20017 - MultipleCaptureSessionsError

상태 코드: 400

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

원인

V1 지문 UUID들이 두 개 이상의 캡처 세션에 분산되어 있음

해결 방법

단일 캡처 세션의 지문 UUID만 사용

세션 관련 에러

PETNOWB2B20010 - NoSuchCaptureSessionException

상태 코드: 404

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

원인

존재하지 않는 세션 ID
세션이 만료됨

해결 방법

세션 ID 확인
새 세션 생성

리소스 관련 에러 (404)

PETNOWB2B20000 - NoSuchPetException

상태 코드: 404

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

원인

존재하지 않는 펫 ID
삭제된 펫

해결 방법

펫 ID 확인
펫 목록 조회로 존재 여부 확인

PETNOWB2B20004 - NoSuchFingerprintAdditionJobException

상태 코드: 404

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

원인

존재하지 않는 지문 추가 작업 ID

해결 방법

작업 ID 확인
새 작업 시작

PETNOWB2B20005 - NoSuchPetVerificationJobException

상태 코드: 404

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

원인

존재하지 않는 검증 작업 ID

해결 방법

작업 ID 확인
새 검증 작업 시작

PETNOWB2B20006 - NoSuchPetIdentificationJobException

상태 코드: 404

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

원인

존재하지 않는 식별 작업 ID

해결 방법

작업 ID 확인
새 식별 작업 시작

PETNOWB2B20016 - NoSuchSearchPoolError

상태 코드: 404

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

원인

존재하지 않는 검색 풀 이름

해결 방법

올바른 검색 풀 이름 확인
Petnow 담당자에게 검색 풀 설정 문의

Web Integration 에러 (Hosted Sessions)

Server Integration 엔드포인트(/v2/hosted-sessions, /v2/hosted-results)에서 반환됩니다. 응답 형식은 동일하게 { "errors": [{ "code": "..." }] }이며, PETNOWB2B10000, PETNOWB2B10001, PETNOWB2B10005, PETNOWB2B10010, PETNOWB2B10011, PETNOWB2B10012, PETNOWB2B20015도 위와 같은 의미로 반환될 수 있습니다.

코드	HTTP	원인	해결 방법
`PETNOWB2B21001`	409	`REGISTER`: 해당 `externalPetId`에 이미 활성 등록이 있음	다른 ID를 사용하거나, 콘솔에서 기존 펫을 먼저 삭제
`PETNOWB2B21002`	404	`VERIFY`: 해당 `externalPetId`에 활성 등록이 없음	먼저 Web Integration으로 등록 (SDK / Server API로 등록한 펫에는 매핑이 없음)
`PETNOWB2B21003`	400	`redirectUrl`이 허용 목록에 없음 (정확 일치)	Integration → Links → 허용 Redirect URL에 URL을 미리 등록
`PETNOWB2B21004`	404	세션을 찾을 수 없음	발급 시 저장한 세션 `id` 확인
`PETNOWB2B21005`	404	결과 코드가 없거나 만료됐거나 종류가 다름 (`/v2` 경로에 Link Integration 표시용 코드를 보낸 경우)	`GET /v2/hosted-sessions/{id}`로 대체 조회
`PETNOWB2B21006`	410	결과 코드가 이미 소비되었고 유예 시간이 지남	`GET /v2/hosted-sessions/{id}`로 세션 조회

서버 에러 (500)

PETNOWB2B30002 - UnknownSpeciesException

상태 코드: 500

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

원인

알 수 없는 펫 종류

해결 방법

species 값이 DOG 또는 CAT인지 확인

에러 핸들링 권장사항

재시도 로직

import time
import requests

def api_request_with_retry(url, method="GET", max_retries=3, **kwargs):
    for attempt in range(max_retries):
        try:
            response = requests.request(method, url, **kwargs)
            
            if response.status_code >= 500:
                time.sleep(2 ** attempt)  # 지수 백오프
                continue
            
            return response
            
        except requests.exceptions.RequestException as e:
            if attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt)
    
    return response

에러 코드별 처리

async function handleApiError(response) {
  const body = await response.json();
  const errorCode = body.errors?.[0]?.code;
  
  switch (errorCode) {
    case "PETNOWB2B10000":
      // 인증 에러: API Key 확인 필요
      console.error("Authentication error: Invalid API key");
      break;

    case "PETNOWB2B10001":
      // 유효성 검사 에러: details 필드에서 실패 항목 확인
      console.error("Validation error:", body.errors?.[0]?.details);
      break;

    case "PETNOWB2B10005":
      // 결제 필요: 펫 등록 한도 초과
      console.warn("Pet limit exceeded. Please upgrade your plan.");
      break;

    case "PETNOWB2B10011":
      // 결제 필요: 현재 플랜에 식별 미포함
      console.warn("Identification is not in your plan. Please upgrade.");
      break;

    case "PETNOWB2B10012":
      // 결제 필요: 플랜 미선택 (아무 플랜이나 선택하면 해제됨)
      console.warn("Please select a plan to enable identification.");
      break;
      
    case "PETNOWB2B20000":
    case "PETNOWB2B20010":
      // 리소스 없음: 재생성 필요
      console.warn("Resource not found");
      break;
      
    default:
      console.error("API error:", errorCode);
  }
}

지원 요청

에러가 해결되지 않는 경우, 다음 정보와 함께 Petnow 담당자에게 문의하세요:

필수 정보

에러 코드 및 메시지
HTTP 상태 코드
요청 URL 및 파라미터
발생 시각 (UTC)
API Key (마스킹 처리)

연락처

이메일: support@petnow.io

에러 코드

On this page