Petnow LogoPetnow
Server API

에러 코드

Petnow Server API의 에러 코드와 해결 방법을 안내합니다.

개요

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

에러 응답 형식

{
  "errors": [
    {
      "code": "PETNOWB2B10000"
    }
  ]
}
필드타입설명
errorsarray에러 배열
errors[].codestring에러 코드 (PETNOWB2BXXXXX 형식)

HTTP 상태 코드

상태 코드설명
200성공
201리소스 생성 성공
204삭제 성공 (응답 본문 없음)
400잘못된 요청
401인증 실패
402결제 필요
403권한 없음
404리소스 없음
500서버 내부 오류

인증 관련 에러 (401)

PETNOWB2B10000 - InvalidApiKeyException

상태 코드: 401

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

원인

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

해결 방법

  1. x-petnow-api-key 헤더 확인
  2. 환경(Staging/Production)에 맞는 Key 사용
  3. Petnow 담당자에게 Key 상태 확인 요청

PETNOWB2B10001 - ValidationError

상태 코드: 400

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

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

원인

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

해결 방법

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

결제 관련 에러 (402)

PETNOWB2B10005 - PetLimitExceededError

상태 코드: 402

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

원인

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

해결 방법

  1. Petnow 담당자에게 유료 플랜 업그레이드 문의

요청 관련 에러 (400)

PETNOWB2B20007 - PetAlreadyHasFingerprintAdditionJobException

상태 코드: 400

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

원인

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

해결 방법

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

PETNOWB2B20009 - PetHasNoFingerprintException

상태 코드: 400

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

원인

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

해결 방법

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

PETNOWB2B20011 - NoPetIdCaptureSessionException

상태 코드: 400

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

원인

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

해결 방법

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

PETNOWB2B20012 - CaptureSessionIsNotFinishedException

상태 코드: 400

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

원인

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

해결 방법

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

PETNOWB2B20013 - InvalidSessionPurposeError

상태 코드: 400

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

원인

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

해결 방법

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

PETNOWB2B20014 - CaptureSessionAlreadyUsedError

상태 코드: 400

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

원인

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

해결 방법

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

PETNOWB2B20015 - SpeciesMismatchError

상태 코드: 400

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

원인

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

해결 방법

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

PETNOWB2B20017 - MultipleCaptureSessionsError

상태 코드: 400

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

원인

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

해결 방법

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

세션 관련 에러

PETNOWB2B20010 - NoSuchCaptureSessionException

상태 코드: 404

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

원인

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

해결 방법

  1. 세션 ID 확인
  2. 새 세션 생성

리소스 관련 에러 (404)

PETNOWB2B20000 - NoSuchPetException

상태 코드: 404

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

원인

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

해결 방법

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

PETNOWB2B20004 - NoSuchFingerprintAdditionJobException

상태 코드: 404

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

원인

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

해결 방법

  1. 작업 ID 확인
  2. 새 작업 시작

PETNOWB2B20005 - NoSuchPetVerificationJobException

상태 코드: 404

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

원인

  • 존재하지 않는 검증 작업 ID

해결 방법

  1. 작업 ID 확인
  2. 새 검증 작업 시작

PETNOWB2B20006 - NoSuchPetIdentificationJobException

상태 코드: 404

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

원인

  • 존재하지 않는 식별 작업 ID

해결 방법

  1. 작업 ID 확인
  2. 새 식별 작업 시작

PETNOWB2B20016 - NoSuchSearchPoolError

상태 코드: 404

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

원인

  • 존재하지 않는 검색 풀 이름

해결 방법

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

서버 에러 (500)

PETNOWB2B30002 - UnknownSpeciesException

상태 코드: 500

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

원인

  • 알 수 없는 펫 종류

해결 방법

  1. 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 == 429:
                time.sleep(60)  # Rate limit 대기
                continue
            
            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 "PETNOWB2B20000":
    case "PETNOWB2B20010":
      // 리소스 없음: 재생성 필요
      console.warn("Resource not found");
      break;
      
    default:
      console.error("API error:", errorCode);
  }
}

지원 요청

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

필수 정보

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

연락처

등록/검증/식별

반려동물 지문 등록, 검증(1:1), 식별(1:N) API를 안내합니다.

최신 버전

SDK 최신 버전 변경사항

On this page

개요에러 응답 형식HTTP 상태 코드인증 관련 에러 (401)PETNOWB2B10000 - InvalidApiKeyExceptionPETNOWB2B10001 - ValidationError결제 관련 에러 (402)PETNOWB2B10005 - PetLimitExceededError요청 관련 에러 (400)PETNOWB2B20007 - PetAlreadyHasFingerprintAdditionJobExceptionPETNOWB2B20009 - PetHasNoFingerprintExceptionPETNOWB2B20011 - NoPetIdCaptureSessionExceptionPETNOWB2B20012 - CaptureSessionIsNotFinishedExceptionPETNOWB2B20013 - InvalidSessionPurposeErrorPETNOWB2B20014 - CaptureSessionAlreadyUsedErrorPETNOWB2B20015 - SpeciesMismatchErrorPETNOWB2B20017 - MultipleCaptureSessionsError세션 관련 에러PETNOWB2B20010 - NoSuchCaptureSessionException리소스 관련 에러 (404)PETNOWB2B20000 - NoSuchPetExceptionPETNOWB2B20004 - NoSuchFingerprintAdditionJobExceptionPETNOWB2B20005 - NoSuchPetVerificationJobExceptionPETNOWB2B20006 - NoSuchPetIdentificationJobExceptionPETNOWB2B20016 - NoSuchSearchPoolError서버 에러 (500)PETNOWB2B30002 - UnknownSpeciesException에러 핸들링 권장사항재시도 로직에러 코드별 처리지원 요청