Error Codes

Overview

Petnow API returns detailed error information along with HTTP status codes when an error occurs.

Error Response Format

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

HTTP Status Codes

Authentication Errors (401)

PETNOWB2B10000 - InvalidApiKeyException

Status Code: 401

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

Cause

• Invalid API Key
• Missing API Key
• Deactivated API Key

Solution

1. Check x-petnow-api-key header
2. Use the correct API Key issued from the Petify Console
3. Contact Petnow representative to verify Key status

PETNOWB2B10001 - ValidationError

Status Code: 400

This error occurs when request parameter validation fails. Unlike other error codes, it provides specific validation error details via the details field.

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

Cause

• Missing required parameters
• Invalid type or format for parameter values
• Disallowed enum values (e.g., a value other than DOG or CAT for species)

Solution

1. Check the details field for the failed field names and error messages
2. Fix the request parameters and retry

Payment Required Errors (402)

PETNOWB2B10005 - PetLimitExceededError

Status Code: 402

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

Cause

• Demo plan maximum pet registration count exceeded

Solution

1. Contact Petnow representative to upgrade to a paid plan

Request Errors (400)

PETNOWB2B20007 - PetAlreadyHasFingerprintAdditionJobException

Status Code: 400

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

Cause

• Pet already has an ongoing fingerprint addition job

Solution

1. Wait for the existing job to complete
2. Retry after polling job status

PETNOWB2B20009 - PetHasNoFingerprintException

Status Code: 400

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

Cause

• Pet has no registered fingerprints during verification

Solution

1. Complete fingerprint registration first
2. Add fingerprints via addFingerprints endpoint

PETNOWB2B20011 - NoPetIdCaptureSessionException

Status Code: 400

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

Cause

• Missing petId when creating session with PET_PROFILE_REGISTRATION or PET_VERIFICATION purpose

Solution

1. Include petId parameter when creating session
2. PET_IDENTIFICATION does not require petId

PETNOWB2B20012 - CaptureSessionIsNotFinishedException

Status Code: 400

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

Cause

• Attempting to perform action while capture session is not yet finished
• Appearance image(s) not uploaded to the session (required for every purpose)

Solution

1. Ensure sufficient files are uploaded to the session
2. Upload the appearance image(s) the UI module provides before performing the action
3. Check session status

PETNOWB2B20013 - InvalidSessionPurposeError

Status Code: 400

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

Cause

• Capture session purpose does not match the requested operation
• Example: Attempting fingerprint registration with a PET_IDENTIFICATION session

Solution

1. Create a session with the correct purpose
2. Choose the appropriate purpose among PET_PROFILE_REGISTRATION, PET_VERIFICATION, PET_IDENTIFICATION

PETNOWB2B20014 - CaptureSessionAlreadyUsedError

Status Code: 400

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

Cause

• Attempting to reuse a capture session that has already been used

Solution

1. Create a new capture session and retry

PETNOWB2B20015 - SpeciesMismatchError

Status Code: 400

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

Cause

• Capture session species does not match the pet's species

Solution

1. Create a session with the same species as the pet
2. Verify the correct pet ID

PETNOWB2B20017 - MultipleCaptureSessionsError

Status Code: 400

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

Cause

• V1 fingerprint UUIDs belong to more than one capture session

Solution

1. Use fingerprint UUIDs from a single capture session only

Session Errors

PETNOWB2B20010 - NoSuchCaptureSessionException

Status Code: 404

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

Cause

• Session ID does not exist
• Session has expired

Solution

1. Verify session ID
2. Create a new session

Resource Errors (404)

PETNOWB2B20000 - NoSuchPetException

Status Code: 404

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

Cause

• Pet ID does not exist
• Pet has been deleted

Solution

1. Verify pet ID
2. Check existence via pet list endpoint

PETNOWB2B20004 - NoSuchFingerprintAdditionJobException

Status Code: 404

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

Cause

• Fingerprint addition job ID does not exist

Solution

1. Verify job ID
2. Start a new job

PETNOWB2B20005 - NoSuchPetVerificationJobException

Status Code: 404

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

Cause

• Verification job ID does not exist

Solution

1. Verify job ID
2. Start a new verification job

PETNOWB2B20006 - NoSuchPetIdentificationJobException

Status Code: 404

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

Cause

• Identification job ID does not exist

Solution

1. Verify job ID
2. Start a new identification job

PETNOWB2B20016 - NoSuchSearchPoolError

Status Code: 404

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

Cause

• Search pool name does not exist

Solution

1. Verify the correct search pool name
2. Contact Petnow representative to configure the search pool

Server Errors (500)

PETNOWB2B30002 - UnknownSpeciesException

Status Code: 500

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

Cause

• Unknown pet species

Solution

1. Verify species value is DOG or CAT

Error Handling Recommendations

Retry Logic

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 wait
                continue
            
            if response.status_code >= 500:
                time.sleep(2 ** attempt)  # Exponential backoff
                continue
            
            return response
            
        except requests.exceptions.RequestException as e:
            if attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt)
    
    return response

Error Code Handling

async function handleApiError(response) {
  const body = await response.json();
  const errorCode = body.errors?.[0]?.code;
  
  switch (errorCode) {
    case "PETNOWB2B10000":
      // Authentication error: Check API key
      console.error("Authentication error: Invalid API key");
      break;

    case "PETNOWB2B10001":
      // Validation error: Check details field for failed fields
      console.error("Validation error:", body.errors?.[0]?.details);
      break;

    case "PETNOWB2B10005":
      // Payment required: Pet registration limit exceeded
      console.warn("Pet limit exceeded. Please upgrade your plan.");
      break;
      
    case "PETNOWB2B20000":
    case "PETNOWB2B20010":
      // Resource not found: Need to recreate
      console.warn("Resource not found");
      break;
      
    default:
      console.error("API error:", errorCode);
  }
}

Support Request

If errors persist, contact Petnow representative with the following information:

Required Information

• Error code and message
• HTTP status code
• Request URL and parameters
• Timestamp (UTC)
• API Key (masked)

Contact

• Email: support@petnow.io