트러블슈팅

개요

이 문서는 Petnow SDK 사용 중 발생할 수 있는 플랫폼 무관한 일반적인 문제들과 해결 방법을 다룹니다. 플랫폼별 상세 내용은 각 플랫폼 문서를 참고하세요.

API 인증 문제

API Key 인증 실패

증상

API 호출 시 401 Unauthorized, 에러 코드 PETNOWB2B10000 반환
계정의 API 사용이 정지된 경우 403 Forbidden, 에러 코드 PETNOWB2B10010 반환

원인

잘못된 API Key (키 오기 또는 공백·특수문자 혼입)
API Key가 비활성화됨 (Petify Console에서 비활성화하거나 로테이션한 경우). Bundle ID 바인딩이나 키 만료는 존재하지 않으므로 이 에러의 원인이 아닙니다.
PETNOWB2B10010 (403): 결제수단 문제로 계정의 API 사용이 정지된 경우 — 키 문제가 아님.

해결 방법

API Key 확인 — 올바른 키인지, 공백·특수문자가 섞이지 않았는지 확인.
Petify Console에서 키가 활성 상태인지 확인하고, 비활성화된 경우 재발급(새 키 생성). 비활성화된 키는 재활성화할 수 없습니다.
PETNOWB2B10010인 경우 Petify Console에서 결제수단 문제를 해결.

생체 정보 업로드 문제

이미지 업로드 실패

증상

파일 업로드 시 타임아웃 또는 네트워크 에러
작업이 생성되기 전에 업로드가 거부됨

원인

파일 크기 제한 초과 (권장: 5MB 이하)
네트워크 연결 불안정
잘못된 파일 형식 (JPEG만 지원)

해결 방법

이미지 압축
- JPEG 품질을 80-90%로 조정
- 해상도를 적정 크기로 조정 (1920x1080 권장)
재시도 로직 구현
- 지수 백오프(exponential backoff) 사용
- 최대 3회 재시도 권장
파일 형식 확인
- JPEG 형식만 업로드
- 파일 확장자와 실제 형식 일치 확인

Job 폴링 타임아웃

증상

Job 상태가 계속 PENDING 상태로 유지
최종 결과를 받지 못함

원인

서버 처리 지연 (이미지 품질이 낮거나 복잡한 경우)
Job ID가 잘못됨
폴링 간격이 너무 짧거나 타임아웃이 너무 짧음

해결 방법

폴링 설정 최적화
- 폴링 간격: 2-3초 권장
- 최대 대기 시간: 60초 권장
Job 상태별 처리
- PENDING: 계속 폴링
- SUCCESS: 결과 처리
- FAILED: 에러 처리 및 재시도
타임아웃 시 재업로드
- 새로운 Job으로 재시도

캡처 세션 관련 문제

증상

PETNOWB2B20010 — 세션 ID가 존재하지 않거나 세션이 만료됨
PETNOWB2B20014 — 해당 세션으로 이미 등록/식별/검증 작업을 수행함

원인

세션이 만료됨
이미 작업에 쓴 세션을 재사용 — 캡처 세션은 1회용입니다
잘못된 세션 ID

전체 목록은 에러 코드를 참고하세요.

해결 방법

새 캡처 세션 생성
세션 생성 후 빠르게 업로드 및 종료 처리
세션 ID를 올바르게 저장하고 전달

펫 프로필 관리 문제

메타데이터 파싱 실패

증상

메타데이터 조회 시 JSON 파싱 에러
특정 필드가 null이거나 누락됨

원인

잘못된 JSON 형식으로 저장됨
인코딩/디코딩 불일치
특수문자 처리 오류

해결 방법

메타데이터 저장 시 검증
- 유효한 JSON 형식인지 확인
- UTF-8 인코딩 사용
안전한 파싱 구현
- Optional 필드 처리
- 기본값 제공
- try-catch로 에러 핸들링
메타데이터 스키마 문서화
- 필수 필드 정의
- 데이터 타입 명시

펫 목록 조회 시 일부 펫만 반환

증상

펫 목록 조회 시 일부 펫만 조회됨
등록한 펫이 목록에 없음

원인

다른 API Key로 등록된 펫
펫이 삭제됨
서버 필터링 (향후 페이지네이션 지원 시)

해결 방법

올바른 API Key 사용 확인
특정 펫 ID로 직접 조회 시도
- GET /v2/pets/{petId}로 존재 여부 확인
펫 등록 후 즉시 목록 새로고침

촬영(SDK) 문제

사진이나 화면으로 테스트할 때

증상

카메라가 코/얼굴은 검출하지만 촬영이 시작되지 않음(검출 상태에 머무름)
사진, 인쇄물, 강아지가 표시된 모니터를 비추면 끝까지 진행되지 않음

원인

SDK의 위조 이미지(fake-image) 분류기가 사진·인쇄물·화면을 거부합니다. 검출은 되지만 실제 동물이 아닌 것으로 분류되어 촬영이 시작되지 않습니다.

해결 방법

실제 동물로 테스트하세요
동물 없이 전체 파이프라인을 검증하려면 Web Integration 체험(mock) 링크를 사용하세요 — 세션이 카메라를 건너뛰고 내장 샘플 반려동물을 사용합니다

종별 촬영 가이드

강아지 (비문)

카메라와 코 사이 거리를 약 30–50 cm로 유지
밝은 실내 조명을 사용하고 직사광선과 강한 그림자는 피하기
지문(코) 이미지를 5장 이상 등록

고양이 (정면 얼굴)

고양이는 정면 얼굴로 식별합니다. 머리가 옆으로 돌아가거나, 위로 들리거나, 아래로 숙여지면 SDK가 각각 NotFrontCatFaceHor / NotFrontCatFaceTop / NotFrontCatFaceBottom을 보고합니다.
보호자가 고양이 얼굴을 카메라 높이로 가져와 정면을 향하게 하도록 안내하세요.

고양이 전용 거리·조명 수치와 최소 촬영 월령(kitten age)은 아직 공개되지 않았으며, 새끼 고양이에서 성묘까지의 동일 개체 식별 지속성도 아직 검증되지 않았습니다. 관련 현장 데이터가 있다면 support@petnow.io로 공유해 주세요.

식별/검증 문제

Verify 정확도 낮음 (1:1 매칭)

증상

같은 펫인데 isVerified: false 반환
신뢰도(score) 점수가 낮음

원인

등록 시와 검증 시 이미지 품질 차이
조명, 각도, 초점 등 촬영 조건 차이
등록된 생체 정보가 부족 (지문 1-2장만 등록)

해결 방법

등록 시 충분한 생체 정보 제공
- 지문(코) 이미지: 최소 5장 이상
- 외형 이미지: 다양한 각도에서 촬영
일관된 촬영 조건 유지
- 자연광 또는 균일한 조명
- 정면 각도 유지
- 선명한 초점
신뢰도 임계값 조정
- 비즈니스 요구사항에 맞게 임계값 설정
- 낮은 신뢰도 시 추가 확인 로직 구현
다른 펫에 대해 높은 유사도 점수가 나올 수 있으므로, 점수를 자체 컨텍스트(종, 메타데이터, 사용자 확인)와 함께 판단하세요

Identify 결과가 너무 많음 (1:N 매칭)

증상

식별 결과에 관련 없는 펫들이 포함됨
Top 1 결과의 신뢰도가 낮음

원인

데이터베이스에 유사한 외형의 펫이 많음
업로드한 이미지 품질이 낮음
임계값 설정이 너무 낮음

해결 방법

신뢰도 기반 필터링
- 상위 N개만 표시 (예: Top 3)
- 최소 신뢰도 임계값 적용 (예: 70 이상)
추가 메타데이터로 필터링
- 종(species), 품종, 지역 등으로 사전 필터링
사용자 확인 프로세스 추가
- 결과를 사용자에게 보여주고 선택하게 함
다른 펫에 대해 높은 유사도 점수가 나올 수 있으므로, 점수를 자체 컨텍스트(종, 메타데이터, 사용자 확인)와 함께 판단하세요

네트워크 문제

간헐적 타임아웃

증상

API 호출이 가끔 타임아웃됨
네트워크 상태가 좋은데도 실패

원인

서버 부하
클라이언트 타임아웃 설정이 너무 짧음
프록시 또는 방화벽 설정

해결 방법

타임아웃 증가
- 요청 타임아웃: 30초 이상
- 리소스 타임아웃: 60초 이상
재시도 로직 구현
- 지수 백오프 사용
- 최대 재시도 횟수 설정
네트워크 상태 확인 후 요청
- 네트워크 연결 여부 확인
- 연결 상태 변화 모니터링

CORS 에러 (웹 환경)

증상

브라우저에서 CORS 정책 위반 에러
Access-Control-Allow-Origin 관련 에러

원인

웹 환경에서 직접 API 호출 시 CORS 제한

해결 방법

백엔드 프록시 사용
- 클라이언트 → 자사 백엔드 → Petnow API
Petnow 담당자에게 도메인 등록 요청
- 허용된 Origin 추가 요청

성능 및 최적화

API 호출 과다

증상

짧은 시간에 너무 많은 API 호출
불필요한 서버 부하 및 비용 증가

원인

불필요한 중복 호출
폴링 간격이 너무 짧음
캐싱 미사용

해결 방법

응답 캐싱
- 펫 목록, 펫 정보는 로컬 캐시 사용
- TTL 설정 (예: 5분)
폴링 최적화
- Job 폴링 간격: 2-3초
- 최대 폴링 횟수 제한
Debouncing/Throttling 적용
- 연속된 요청 방지

메모리 사용량 증가

증상

이미지 업로드 후 메모리 누수
앱이 점점 느려짐

원인

이미지 데이터가 메모리에 계속 유지됨
캐시가 무제한 증가
리소스 정리 누락

해결 방법

이미지 처리 후 즉시 해제
- 업로드 완료 후 원본 데이터 해제
- 임시 파일 삭제
캐시 크기 제한
- 최대 캐시 크기 설정 (예: 100MB)
- LRU 정책 사용
메모리 경고 처리
- 시스템 메모리 경고 시 캐시 정리

에러 코드

Server API의 에러는 PETNOWB2B... 코드와 HTTP 상태로 반환됩니다. 전체 코드 목록과 원인·해결 방법은 Server API – 에러 코드를 참고하세요.

디버깅 팁

1. 에러 응답 상세 확인

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

3. 네트워크 트래픽 모니터링

개발자 도구에서 네트워크 요청 확인
요청/응답 헤더, 바디 검사
타이밍 정보 분석

4. 로그 수집

API 호출 시각, 파라미터, 응답 기록
에러 발생 시 전체 컨텍스트 저장
재현 가능한 테스트 케이스 작성

지원 요청

위의 해결 방법으로 문제가 해결되지 않는 경우, 다음 정보와 함께 Petnow 담당자에게 문의해주세요:

필수 정보

API Key (또는 마스킹된 형태)
발생 시각 (UTC 또는 로컬 타임존 명시)
요청 파라미터 (민감 정보 제외)
에러 메시지 및 HTTP 상태 코드
SDK 버전 및 플랫폼 정보

선택 정보

재현 단계
스크린샷 또는 로그 파일
네트워크 환경 (WiFi, 4G/5G 등)
예상 동작과 실제 동작 차이

연락처

이메일: support@petnow.io
담당자 직접 연락 (계약 시 제공된 연락처)

트러블슈팅

On this page