트러블슈팅

개요

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

API 인증 문제

API Key 인증 실패 (401 Unauthorized)

증상

• API 호출 시 401 Unauthorized 에러 발생
• INVALID_API_KEY 에러 메시지

원인

1. 잘못된 API Key 사용
2. Bundle ID가 등록된 API Key와 불일치
3. API Key 만료 또는 비활성화

해결 방법

1. API Key 확인
   • 올바른 API Key 사용 확인
   • API Key에 공백이나 특수문자 포함 여부 확인
2. Bundle ID 매칭 확인
   • 앱의 실제 Bundle ID와 등록된 Bundle ID 일치 여부 확인
3. Petnow 담당자에게 API Key 상태 확인 요청

생체 정보 업로드 문제

이미지 업로드 실패

증상

• 파일 업로드 시 타임아웃 또는 네트워크 에러
• FILE_TOO_LARGE 에러

원인

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

해결 방법

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

Job 폴링 타임아웃

증상

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

원인

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

해결 방법

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

캡처 세션 관련 문제

증상

• SESSION_NOT_FOUND 에러
• SESSION_ALREADY_ENDED 에러
• SESSION_TIMEOUT 에러

원인

1. 세션이 만료됨
2. 이미 종료된 세션에 업로드 시도
3. 잘못된 세션 ID

해결 방법

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

펫 프로필 관리 문제

메타데이터 파싱 실패

증상

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

원인

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

해결 방법

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

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

증상

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

원인

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

해결 방법

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

식별/검증 문제

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

증상

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

원인

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

해결 방법

1. 등록 시 충분한 생체 정보 제공
   • 지문(코) 이미지: 최소 5장 이상
   • 외형 이미지: 다양한 각도에서 촬영
2. 일관된 촬영 조건 유지
   • 자연광 또는 균일한 조명
   • 정면 각도 유지
   • 선명한 초점
3. 신뢰도 임계값 조정
   • 비즈니스 요구사항에 맞게 임계값 설정
   • 낮은 신뢰도 시 추가 확인 로직 구현

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

증상

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

원인

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

해결 방법

1. 신뢰도 기반 필터링
   • 상위 N개만 표시 (예: Top 3)
   • 최소 신뢰도 임계값 적용 (예: 70 이상)
2. 추가 메타데이터로 필터링
   • 종(species), 품종, 지역 등으로 사전 필터링
3. 사용자 확인 프로세스 추가
   • 결과를 사용자에게 보여주고 선택하게 함

네트워크 문제

간헐적 타임아웃

증상

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

원인

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

해결 방법

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

CORS 에러 (웹 환경)

증상

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

원인

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

해결 방법

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

성능 및 최적화

API 호출 과다

증상

• 짧은 시간에 너무 많은 API 호출
• Rate limit 에러 (429 Too Many Requests)

원인

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

해결 방법

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

메모리 사용량 증가

증상

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

원인

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

해결 방법

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

일반적인 에러 코드

디버깅 팁

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
• 담당자 직접 연락 (계약 시 제공된 연락처)