9. 다운로드 에러 코드
SDK 에러 코드
com.kollus.sdk.media.util.ErrorCodes 클래스에 정의된 핵심 에러 코드 규격과 구체적인 발생(트리거) 시점입니다.
| 상수 | 설명 | 트리거 |
|---|---|---|
ERROR_OK | 정상 완료 | — |
ERROR_INCORRECT_AUTH_KEY | SDK 키 만료/오류 | 초기화(initialize) 또는 인증 메서드(setCertification) 호출 시점 |
ERROR_UNSUPPORTED_DEVICE | 지원하지 않는 디바이스 | 디바이스 정보 등록(setDevice) 또는 DRM 호환성 검증 실패 시 |
ERROR_STORAGE_FULL | 저장소 용량 부족 | 메타 정보 로드(load) 및 파일 다운로드(download) 시작 시점 |
ERROR_WRITE_FILE | 파일 쓰기 오류 | 다운로드 진행 중 디스크 입출력 에러 발생 시 |
ERROR_ALREADY_DOWNLOADING | 중복 다운로드 요청 | 동일한 콘텐츠에 대해 download(mck) 호출 시 |
ERROR_ALREADY_DOWNLOADED | 이미 다운로드 완료된 콘텐츠 | 다운로드 완료된 콘텐츠에 대해 download(mck) 호출 시 |
ERROR_NOT_EXIST_DOWNLOADED_CONTENTS | 로컬에 다운로드된 파일 없음 | getDownloadKollusContent(path) 호출 또는 오프라인 재생 시 |
ERROR_EXPIRATION_DATE | 만료일 초과 | 오프라인 재생 시도 시 |
ERROR_EXPIRATION_PLAY_TIME | 허용 재생 시간 초과 | 오프라인 재생 시도 시 |
ERROR_EXPIRATION_COUNT | 허용 재생 횟수 초과 | 오프라인 재생 시도 시 |
ERROR_FORCE_DELETE | DRM 다운로드 콜백(kind 2 또는 kind 3) 응답에 content_delete: 1(또는 content_expired: 1)이 담겨 콘텐츠 강제 삭제 | onDRMInfo 콜백 내에서 DCB_INFO_DELETE 신호 감지 |
SDK 외부 에러
SDK 내부 로직 외에 모바일 운영체제 정책이나 네트워크 오류로 인해 발생할 수 있는 에러 상황 대응 패턴입니다.
- 저장소 권한 거부: 앱 레이어에서
SecurityException또는IOException예외 처리를 구성해야 합니다. 매니페스트 내 권한 선언 상태와 런타임 권한 획득 흐름을 확인하세요. - 네트워크 연결 실패: SDK가 자동으로 재시도를 수행합니다. 자동 재시도 임계치는
storage.setNetworkTimeout(timeout, retryCount)로 조정할 수 있으며,setNetworkTimeout(30, 3)(30초, 3회) 설정을 권장합니다. - 백그라운드 강제 종료: 포그라운드 서비스를 적용하지 않으면 운영체제가 다운로드 프로세스를 임의로 종료합니다.
FOREGROUND_SERVICE_TYPE_DATA_SYNC속성을 함께 사용해야 합니다. (참고: 1. 다운로드 준비)
에러 코드별 추천 사용자 메시지
| 에러 코드 | 사용자 메시지 예시 |
|---|---|
ERROR_INCORRECT_AUTH_KEY | "앱 인증에 문제가 발생했습니다. 앱을 최신 버전으로 업데이트해 주세요." |
ERROR_STORAGE_FULL | "기기의 저장 공간이 부족합니다. 시청을 완료한 다운로드 파일을 삭제하거나 저장 공간을 확보해 주세요." |
ERROR_WRITE_FILE | "파일 저장에 실패했습니다. 잠시 후 다시 시도해 주세요." |
ERROR_EXPIRATION_* | "콘텐츠 시청 기간이 만료되었습니다. 네트워크를 연결하여 라이선스를 갱신해 주세요." |
ERROR_UNSUPPORTED_DEVICE | "이 기기에서는 콘텐츠를 다운로드하거나 재생할 수 없습니다." |