본문으로 건너뛰기

3XXX (Web Player/HTML5 Player for All 에러)

Web Player(v5) 및 HTML5 Player for All(v4)에서 발생하는 에러 코드입니다. error 이벤트 발생 시 get_error_detail() 메서드로 코드를 확인합니다.

controller.on('error', function() {
  var detail = controller.get_error_detail();
  console.error('에러 코드:', detail.code, detail.message);
});

3000​

  • 에러 코드: 3000
  • 타입: ERROR_API_CONNECTION
  • 요약: 플레이어 초기화 시 Kollus 서버 API 호출 실패

원인​

  • 사용자의 인터넷 네트워크가 일시적으로 단절된 경우입니다.
  • Kollus 서버 인프라에 일시적인 장애가 발생한 경우입니다.
  • 서비스 사이트의 CSP(콘텐츠 보안 정책)로 인해 Kollus 통신 도메인이 차단된 상태입니다.

해결 방법​

  • 사용자의 인터넷 네트워크 연결 상태를 확인한 후 브라우저 페이지를 새로고침하세요.
  • 고객사 서비스 웹사이트에 CSP가 설정되어 있다면, 방화벽 및 보안 화이트리스트에 *.kollus.com 도메인이 정상적으로 허용되어 있는지 확인하세요.

3001​

  • 에러 코드: 3001
  • 타입: MEDIA_ERR_ABORTED
  • 요약: 사용자 또는 브라우저에 의한 재생 취소

원인​

사용자가 영상을 시청하던 중 브라우저 탭을 전환하거나 다른 페이지로 이동(네비게이션)하는 등, 의도된 동작에 의해 미디어 로딩이 중단되는 현상입니다. 대부분 정상적인 서비스 이용 흐름이므로 별도의 예외 에러 처리를 구성할 필요는 없습니다.

3002​

  • 에러 코드: 3002
  • 타입: MEDIA_ERR_NETWORK
  • 요약: 영상 재생 중 네트워크 연결 유실

해결 방법​

네트워크 재연결 상태를 감지한 후 시스템이 자동으로 재생을 재시도하게 하거나, 사용자 UI 화면에 수동 재시도 버튼을 제공하는 로직을 구현하세요.

controller.on('error', function() {
  var detail = controller.get_error_detail();
  if (detail.code === 3002) {
    showRetryButton();
  }
});

3005​

  • 에러 코드: 3005
  • 타입: MEDIA_ERR_ENCRYPTED
  • 요약: 현재 재생 환경에서 암호화 콘텐츠 미지원

원인​

  • 비암호화 콘텐츠 전용인 HTML5 Player for All(v4) 환경에서 DRM 보안 정책이 적용된 암호화 콘텐츠의 재생을 시도한 경우입니다.
  • 사용자가 이용 중인 웹 브라우저 환경이 EME(Encrypted Media Extensions) 기능을 지원하지 않는 구형 브라우저인 경우입니다.

해결 방법​

암호화(DRM) 콘텐츠는 HTML5 Player for PC (Hybrid) 또는 Multi DRM 환경에서 재생해야 합니다.

  • HTML5 Player for PC (Hybrid): Microsoft Edge 또는 Chrome 45 이상에서 암호화 콘텐츠 재생 시 적용되는 하이브리드 형식의 HTML5 플레이어 제품군입니다.

3008​

  • 에러 코드: 3008
  • 타입: ERROR_DUPLICATE_PLAYER
  • 요약: 동일 페이지 내에서 두 개 이상의 플레이어 중복 실행 감지

원인​

  • 단일 웹 페이지 내에 플레이어 호출을 위한 iframe 요소를 여러 개 삽입한 경우입니다.
  • SPA(Single Page Application) 개발 환경에서 기존 플레이어 컴포넌트를 완전히 언마운트(Unmount)하지 않은 상태에서 새로운 플레이어 인스턴스를 동시 마운트한 경우입니다.

해결 방법​

하나의 웹 페이지 안에서는 반드시 단 하나의 플레이어 인스턴스만 활성화되도록 구조를 제어하세요. 플레이어를 교체해야 할 때는 이전에 사용하던 플레이어 객체의 dispose() 메서드를 먼저 호출하여 메모리에서 완전히 해제해야 합니다.

controller.dispose();
// 새로운 플레이어 인스턴스 생성

3012​

  • 에러 코드: 3012
  • 타입: MEDIA_ERR_LIVE_NOT_BROADCASTING
  • 요약: 진행 중인 라이브 방송 없음

원인​

요청한 라이브 채널이 현재 실시간 송출 중이 아니거나, 라이브 방송 일정이 완전히 종료된 상태에서 접속을 시도한 경우에 발생합니다.

해결 방법​

사용자 화면에 해당 라이브 강의의 예정 일정을 안내하는 가이드 문구를 출력하거나, 방송이 시작된 이후 브라우저 화면을 새로고침하여 다시 입장하도록 안내를 구성하세요.

3013​

  • 에러 코드: 3013
  • 타입: ERROR_DUPLICATION_BLOCK_OR_EXPIRED_TIME_MEDIA_KEY
  • 요약: [Live 전용] 중복 재생 차단 또는 재생 허용 시간 만료

원인​

  • 중복 재생 차단: 동일한 사용자 식별자(client_user_id) 데이터를 사용하는 세션이 다른 기기나 브라우저에서 이미 활성화되어 영상을 시청 중인 상태입니다.
  • 재생 허용 시간 만료: JWT의 expt 설정값 또는 미디어 키의 유효 기한(TTL)이 완전히 만료된 상태입니다.

진단​

get_error_detail().message 결과값을 통해 위의 두 가지 세부 원인 중 어느 케이스에 해당하는지 확인합니다.

해결 방법​

  • 중복 재생 차단 케이스: 사용자 화면에 "다른 기기에서 이미 재생 중입니다."와 같은 안내 경고 팝업을 노출하세요.
  • 재생 허용 시간 만료 케이스: JWT 인증 토큰을 새로 발급받아 재생을 다시 요청하세요.

3015​

  • 에러 코드: 3015
  • 타입: ERROR_CONCURRENTLY_VIEWER_LIMIT
  • 요약: 동시 접속 인원 초과

원인​

Kollus Live 콘솔의 라이브 채널 설정에 지정된 최대 동시 시청자 수 임계치(한도)를 초과하여 트래픽이 유입된 경우입니다. 주로 대규모 사용자가 몰리는 실시간 라이브 방송 환경에서 발생합니다.

해결 방법​

  • 사용자 안내 팝업 노출: 화면에 "현재 접속자가 많아 시청이 지연되고 있습니다. 잠시 후 다시 시도해 주세요." 등의 안내 메시지 팝업을 노출하세요.
  • 자동 재시도 로직 구현 팁: 동시 요청 폭주(Thundering Herd) 현상을 방지하기 위해 즉시 재시도 대신 요청 간격을 점진적으로 늘리는 지수 백오프(Exponential Backoff) 알고리즘 방식을 적용할 것을 권장합니다.

3019​

  • 에러 코드: 3019
  • 타입: ERROR_DETECT_MANIPULATION
  • 요약: 플레이어 데이터 위변조 감지

원인​

플레이어 관련 데이터의 위변조가 감지되면 보안 위협으로 간주하여 비디오 재생 프로세스를 즉시 차단합니다. 정상적인 일반 시청자 환경에서는 거의 발생하지 않습니다.