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. Verify the key is active (and re-issue it if needed) in the Petify Console under My Page → API Key Management

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. Upgrade to a paid plan yourself in the Petify Console (My Page → Billing)

PETNOWB2B10011 - IdentificationNotInPlanError

Status Code: 402

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

Cause

• The tenant's plan does not include identification (1:N matching). This is returned by POST /v2/pets:identify and by POST /v2/hosted-sessions with action: IDENTIFY for accounts that are not entitled to identification (Petify Core).
• This code may start being returned in a future release. Handle it now so the change is a non-event.

Solution

1. Upgrade to a plan that includes identification (Petify Plus) in the Petify Console (My Page → Billing)

PETNOWB2B10012 - IdentificationPlanSelectionRequiredError

Status Code: 402

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

Cause

• The account is being migrated from the legacy plan onto Petify Core / Plus and its migration date has passed with no plan chosen, so identification requests are blocked until a plan is selected. Distinct from PETNOWB2B10011: here selecting either plan resolves it.
• This code may start being returned in a future release. Handle it now.

Solution

1. Choose a plan in the Petify Console (My Page → Billing). Selecting either Core or Plus clears this state; identification itself additionally requires Plus.

Forbidden Errors (403)

PETNOWB2B10010 - Account API access suspended

Status Code: 403

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

Cause

• The account's API access is suspended due to a billing/payment-method issue. This is an account-level state, not an API Key problem.

Solution

1. Resolve the billing/payment-method issue in the Petify Console.

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

• No fingerprint image is uploaded to the session
• No appearance image is uploaded to the session (required for every purpose)

Solution

1. Upload the fingerprint images (minimum 5 for registration, 3 for verification/identification)
2. Upload the appearance image(s) the UI module provides
3. Start the action only after every upload has returned 201

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

Web Integration Errors (Hosted Sessions)

Returned by the Server Integration endpoints (/v2/hosted-sessions, /v2/hosted-results). They share the { "errors": [{ "code": "..." }] } shape; PETNOWB2B10000, PETNOWB2B10001, PETNOWB2B10005, PETNOWB2B10010, PETNOWB2B10011, PETNOWB2B10012 and PETNOWB2B20015 can also be returned there with the meanings above.

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 >= 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 "PETNOWB2B10011":
      // Payment required: identification not included in the current plan
      console.warn("Identification is not in your plan. Please upgrade.");
      break;

    case "PETNOWB2B10012":
      // Payment required: no plan selected yet (choosing any plan clears this)
      console.warn("Please select a plan to enable identification.");
      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