에러 코드

개요

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`	리소스 없음
`500`	서버 내부 오류

인증 관련 에러 (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 매칭)이 포함되어 있지 않음. 식별 권한이 없는 계정이 POST /v2/pets:identify를 호출하면 반환됩니다.

해결 방법

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

PETNOWB2B10012 - IdentificationPlanSelectionRequiredError

상태 코드: 402

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

원인

아직 플랜을 선택하지 않아 식별 요청이 차단된 상태. PETNOWB2B10011과 달리 아무 플랜이나 선택하면 해제됩니다(기본 플랜은 무료).

해결 방법

Petify Console에서 플랜을 선택하세요 (마이페이지 → 결제). 무료 기본 플랜을 선택하는 것만으로도 이 상태가 해제됩니다.

접근 권한 에러 (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"
    }
  ]
}

원인

캡처 세션이 아직 종료되지 않은 상태에서 작업 수행
외관 이미지가 세션에 업로드되지 않음 (외관 이미지는 모든 용도에서 필수)

해결 방법

세션에 충분한 파일 업로드 확인
작업 수행 전 UI 모듈이 제공하는 외관 이미지 업로드
세션 상태 확인

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 담당자에게 검색 풀 설정 문의

서버 에러 (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