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
  • FILE_TOO_LARGE error

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

  • SESSION_NOT_FOUND error
  • SESSION_ALREADY_ENDED error
  • SESSION_TIMEOUT error

Causes

  1. Session expired
  2. Attempting to upload to already ended session
  3. Incorrect session ID

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

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

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

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 ReturnedIdentification/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