Petnow LogoPetnow

Troubleshooting

Common issues and solutions when using Petnow SDK

Overview

This document covers platform-agnostic common issues that may occur when using Petnow SDK and their solutions. For platform-specific details, please refer to each platform's documentation.

API Authentication Issues

API Key Authentication Failure

Symptoms

  • 401 Unauthorized when calling the API, with error code PETNOWB2B10000
  • 403 Forbidden with PETNOWB2B10010 if the account's API access is suspended

Causes

  1. Incorrect API Key (wrong key, or stray whitespace/special characters)
  2. The API Key has been deactivated (e.g. disabled or rotated in the Petify Console). There is no Bundle ID binding or key expiry, so neither causes this error.
  3. PETNOWB2B10010 (403): the account's API access is suspended due to a billing/payment-method issue — not a key problem.

Solutions

  1. Verify the API Key — confirm it is the correct key with no stray whitespace or special characters.
  2. Confirm the key is active in the Petify Console; if it was deactivated, reissue it (create a new key) — deactivated keys cannot be reactivated.
  3. For PETNOWB2B10010, resolve the billing/payment-method issue in the Petify Console.

Biometric Upload Issues

Image Upload Failure

Symptoms

  • Timeout or network error during file upload
  • The upload is rejected before a job is created

Causes

  1. File size exceeds limit (recommended: under 5MB)
  2. Unstable network connection
  3. Incorrect file format (only JPEG supported)

Solutions

  1. Compress images
    • Adjust JPEG quality to 80-90%
    • Adjust resolution to appropriate size (1920x1080 recommended)
  2. Implement retry logic
    • Use exponential backoff
    • Recommend max 3 retries
  3. Verify file format
    • Upload only JPEG format
    • Confirm file extension matches actual format

Job Polling Timeout

Symptoms

  • Job status remains in PENDING state
  • Unable to receive final result

Causes

  1. Server processing delay (low image quality or complex case)
  2. Incorrect Job ID
  3. Polling interval too short or timeout too short

Solutions

  1. Optimize polling settings
    • Polling interval: 2-3 seconds recommended
    • Max wait time: 60 seconds recommended
  2. Handle by job status
    • PENDING: Continue polling
    • SUCCESS: Process result
    • FAILED: Handle error and retry
  3. Re-upload on timeout
    • Retry with new Job

Capture Session Issues

Symptoms

  • PETNOWB2B20010 — the session id does not exist, or the session has expired
  • PETNOWB2B20014 — the session already backed a register / identify / verify job

Causes

  1. Session expired
  2. Reusing a session that already backed a job — a capture session is single-use
  3. Incorrect session ID

See Error Codes for the full list.

Solutions

  1. Create new capture session
  2. Quickly upload and complete after session creation
  3. Correctly store and pass session ID

Pet Profile Management Issues

Metadata Parsing Failure

Symptoms

  • JSON parsing error when querying metadata
  • Specific fields are null or missing

Causes

  1. Saved in incorrect JSON format
  2. Encoding/decoding mismatch
  3. Special character handling error

Solutions

  1. Validate metadata on save
    • Verify valid JSON format
    • Use UTF-8 encoding
  2. Implement safe parsing
    • Handle optional fields
    • Provide default values
    • Error handling with try-catch
  3. Document metadata schema
    • Define required fields
    • Specify data types

Partial Pet List Returned

Symptoms

  • Only some pets returned when querying pet list
  • Registered pet not in list

Causes

  1. Pet registered with different API Key
  2. Pet was deleted
  3. Server filtering (when pagination is supported in future)

Solutions

  1. Confirm using correct API Key
  2. Try direct query with specific pet ID
    • Check existence with GET /v2/pets/{petId}
  3. Refresh list immediately after pet registration

Capture (SDK) Issues

Testing with Photos or Screens

Symptoms

  • The camera detects the nose/face, but the capture never starts (the status stays at detection)
  • Pointing the camera at a photo, a printed image, or a monitor showing a dog never completes

Cause

  • The SDK's fake-image classifier rejects photos, printed images, and screens. Detection reports the object, but the capture does not start because the frame is classified as not a live animal.

Solutions

  1. Test with a live animal
  2. To exercise the whole pipeline without an animal, use Web Integration trial (mock) links — their sessions skip the camera and use a bundled sample pet

Capture Guidance by Species

Dogs (nose print)

  • Keep the camera about 30–50 cm from the nose
  • Use bright indoor light; avoid direct sunlight and hard shadows
  • Register 5 or more fingerprint (nose) images

Cats (frontal face)

  • Cats are identified from the frontal face. When the head is turned sideways, tilted up, or tilted down, the SDK reports NotFrontCatFaceHor / NotFrontCatFaceTop / NotFrontCatFaceBottom respectively.
  • Instruct the handler to bring the cat's face to camera level and keep it frontal.

Cat-specific distance and lighting figures and a minimum kitten age are not yet published, and identity persistence from kitten to adult has not yet been validated. If you have field data on these, please share it with support@petnow.io.

Identification/Verification Issues

Low Verify Accuracy (1:1 Matching)

Symptoms

  • Same pet returns isVerified: false
  • Low confidence score

Causes

  1. Image quality difference between registration and verification
  2. Different capture conditions (lighting, angle, focus)
  3. Insufficient registered biometric data (only 1-2 fingerprints registered)

Solutions

  1. Provide sufficient biometric data during registration
    • Fingerprint (nose) images: minimum 5 or more
    • Appearance images: captured from various angles
  2. Maintain consistent capture conditions
    • Natural or uniform lighting
    • Maintain frontal angle
    • Sharp focus
  3. Adjust confidence threshold
    • Set threshold according to business requirements
    • Implement additional verification logic for low confidence
  4. A high similarity score against a different pet can occur; combine the score with your own context (species, metadata, user confirmation)

Too Many Identify Results (1:N Matching)

Symptoms

  • Identification results include unrelated pets
  • Low confidence for Top 1 result

Causes

  1. Many pets with similar appearance in database
  2. Low uploaded image quality
  3. Threshold setting too low

Solutions

  1. Filter by confidence
    • Display only top N (e.g., Top 3)
    • Apply minimum confidence threshold (e.g., 70 or above)
  2. Filter with additional metadata
    • Pre-filter by species, breed, region, etc.
  3. Add user confirmation process
    • Show results to user and let them select
  4. A high similarity score against a different pet can occur; combine the score with your own context (species, metadata, user confirmation)

Network Issues

Intermittent Timeouts

Symptoms

  • API calls occasionally timeout
  • Failures even with good network status

Causes

  1. Server load
  2. Client timeout setting too short
  3. Proxy or firewall configuration

Solutions

  1. Increase timeout
    • Request timeout: 30 seconds or more
    • Resource timeout: 60 seconds or more
  2. Implement retry logic
    • Use exponential backoff
    • Set max retry count
  3. Check network status before request
    • Verify network connectivity
    • Monitor connection state changes

CORS Error (Web Environment)

Symptoms

  • CORS policy violation error in browser
  • Access-Control-Allow-Origin related error

Cause

  • CORS restriction when calling API directly from web environment

Solutions

  1. Use backend proxy
    • Client → Your backend → Petnow API
  2. Request domain registration from Petnow representative
    • Request to add allowed Origin

Performance and Optimization

Excessive API Calls

Symptoms

  • Too many API calls in short time
  • Unnecessary server load and cost

Causes

  1. Unnecessary duplicate calls
  2. Polling interval too short
  3. Not using caching

Solutions

  1. Response caching
    • Use local cache for pet list, pet info
    • Set TTL (e.g., 5 minutes)
  2. Optimize polling
    • Job polling interval: 2-3 seconds
    • Limit max polling count
  3. Apply Debouncing/Throttling
    • Prevent consecutive requests

Increasing Memory Usage

Symptoms

  • Memory leak after image upload
  • App gradually slows down

Causes

  1. Image data kept in memory continuously
  2. Unlimited cache growth
  3. Missing resource cleanup

Solutions

  1. Release immediately after image processing
    • Release original data after upload completion
    • Delete temporary files
  2. Limit cache size
    • Set max cache size (e.g., 100MB)
    • Use LRU policy
  3. Handle memory warnings
    • Clear cache on system memory warning

Error Codes

Server API errors are returned with PETNOWB2B... codes and an HTTP status. For the full list of codes with causes and solutions, see Server API – Error Codes.

Debugging Tips

1. Check Error Response Details

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human readable message",
    "field": "problematic_field",
    "details": { "additional": "info" }
  }
}

3. Monitor Network Traffic

  • Check network requests in developer tools
  • Inspect request/response headers, body
  • Analyze timing information

4. Collect Logs

  • Record API call time, parameters, response
  • Save full context when error occurs
  • Create reproducible test cases

Support Request

If the problem is not resolved with the above solutions, please contact Petnow representative with the following information:

Required Information

  • API Key (or masked form)
  • Occurrence time (specify UTC or local timezone)
  • Request parameters (excluding sensitive information)
  • Error message and HTTP status code
  • SDK version and platform information

Optional Information

  • Reproduction steps
  • Screenshots or log files
  • Network environment (WiFi, 4G/5G, etc.)
  • Difference between expected and actual behavior

Contact

  • Email: support@petnow.io
  • Direct contact with representative (contact provided upon contract)

On this page

OverviewAPI Authentication IssuesAPI Key Authentication FailureBiometric Upload IssuesImage Upload FailureJob Polling TimeoutCapture Session IssuesPet Profile Management IssuesMetadata Parsing FailurePartial Pet List ReturnedCapture (SDK) IssuesTesting with Photos or ScreensCapture Guidance by SpeciesIdentification/Verification IssuesLow Verify Accuracy (1:1 Matching)Too Many Identify Results (1:N Matching)Network IssuesIntermittent TimeoutsCORS Error (Web Environment)Performance and OptimizationExcessive API CallsIncreasing Memory UsageError CodesDebugging Tips1. Check Error Response Details3. Monitor Network Traffic4. Collect LogsSupport Request