Troubleshooting

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 (401 Unauthorized)

Symptoms

• 401 Unauthorized error when calling API
• INVALID_API_KEY error message

Causes

1. Using incorrect API Key
2. Bundle ID mismatch with registered API Key
3. API Key expired or deactivated

Solutions

1. Verify API Key
   • Confirm using correct environment (Stage/Prod) Key
   • Check for whitespace or special characters in API Key
2. Verify Bundle ID match
   • Confirm actual app Bundle ID matches registered Bundle ID
3. Contact Petnow representative to verify API Key status

Environment Configuration Error

Symptoms

• Authentication failure when using Prod Key in Stage environment
• Mismatch between isDebugMode setting and API Key

Cause

• Mismatch between isDebugMode flag and API Key environment

Solution

✅ Correct combinations:
- isDebugMode: true + Stage API Key
- isDebugMode: false + Prod API Key

❌ Wrong combinations:
- isDebugMode: true + Prod API Key
- isDebugMode: false + Stage API Key

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 PROCESSING 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
   • PROCESSING: 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
• Rate limit error (429 Too Many Requests)

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

Common Error Codes

Debugging Tips

1. Enable Debug Mode

When isDebugMode: true is set:
- Detailed error messages
- Request/response logs
- Use Stage environment

2. 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)