---
title: "에러 대응"
slug: "vpe-umd-error-handling"
updated: 2026-09-17T09:08:03Z
published: 2026-09-17T09:08:03Z
canonical: "guide.ncloud-docs.com/vpe-umd-error-handling"
stale: true
---

> ## Documentation Index
> Fetch the complete documentation index at: https://guide.ncloud-docs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 에러 대응

Classic/VPC 환경에서 이용 가능합니다.

재생 중 발생하는 에러를 감지하고 처리하는 방법을 설명합니다.

참고

Video Player Enhancement 서비스와 함께 Media Analytics 서비스를 이용하면 Media Analytics 관리 페이지에서 에러 코드를 손쉽게 확인할 수 있습니다.

## 에러 이벤트 감지

플레이어를 호출하는 함수에서 `player.on("error", (err) => {})` 코드로 이벤트를 감지하여 에러 코드와 메시지를 호출할 수 있습니다.

참고

에러 코드는 Video Player Enhancement 서비스에서 제공하는 에러 코드 목록으로 전달됩니다.

```
const player = new ncplayer("video", {
  playlist: [
    {
      file: "http://example.com/myVideo.mp4",
      poster: "http://example.com/myVideoThumb.png",
    },
  ],
});

// error 이벤트 데이터 구조:
// {
//   errorCode: string | null,     // 예: "E0001", "E0004"
//   errorMessage: string | null,  // 에러 설명
//   errorTitle: string | null,    // 에러 제목
// }

player.on("error", function(err) {
  var errorCode = err.errorCode;
  var errorMessage = err.errorMessage;
  var errorTitle = err.errorTitle;

  switch (errorCode) {
    case "E0001":
      console.log("E0001 - ACCESS DENIED");
      console.log(errorTitle, errorMessage);
      break;
    case "E0002":
      console.log("E0002 - NOT AUTHORIZED");
      console.log(errorTitle, errorMessage);
      break;
    case "E0003":
      console.log("E0003 - NETWORK ERROR");
      console.log(errorTitle, errorMessage);
      break;
    case "E0004":
      console.log("E0004 - CANNOT PLAY");
      console.log(errorTitle, errorMessage);
      break;
    case "E0005":
      console.log("E0005 - LICENSE IS INVALID");
      console.log(errorTitle, errorMessage);
      break;
    case "E0006":
      console.log("E0006 - LIMIT DENIED");
      console.log(errorTitle, errorMessage);
      break;
    default:
      break;
  }
});
```

## 재시도 설정

플레이어가 오류를 응답하기 전 최대 재시도 횟수 및 최대 지연 시간 설정을 커스터마이징할 수 있습니다.

참고

- 플레이어 초기화 시 영상 재생 시도 추가: 기본값 최대 3회, 5초 간격
- Live/VOD가 중단되었을 때 재생 시도 추가: 기본값 최대 3회, 5초 간격

```
const player = new ncplayer("video", {
  playlist: [
    {
      file: "https://CDN도메인/example.m3u8",
      poster: "https://CDN도메인/poster.jpg",
    },
  ],
  retry: {
    maxRetry: 10,   // 최대 재시도 횟수
    interval: 5000, // 재시도 횟수당 지연 시간(ms)
  },
});
```

| 옵션 | 타입 | 기본값 | 설명 |
| --- | --- | --- | --- |
| `retry` | Object | - | 재시도 설정 |
| `retry.maxRetry` | Integer | `3` | 최대 재시도 횟수 |
| `retry.interval` | Integer | `5000` | 재시도 지연 시간 (밀리초) |

## 에러 화면 재정의

기본으로 제공되는 에러 화면을 고객사가 원하는 코드로 변경하여 실행할 수 있습니다. 에러 화면을 재정의(override)하면 마지막 재생 위치에서 정지(pause) 상태를 유지한 채 플레이어 오버레이를 통해 에러 화면을 구현할 수 있습니다.

```
// 동영상(MP4)
const player = new ncplayer("video", {
  playlist: [
    {
      file: "https://CDN도메인/example_video_01.mp4",
      poster: "https://CDN도메인/example_image_01.png",
    },
  ],
  override: {
    error: function(err) {
      console.log("player error:", err);

      // 고객사 에러 화면 기능 구현
      // 예: document.getElementById("error-overlay").style.display = "block";
    },
  },
});
```

## 에러 코드

Video Player Enhancement 서비스에서 제공하는 에러 코드 목록은 다음과 같습니다.

| 에러 코드 | 에러 메시지 | 설명 |
| --- | --- | --- |
| E0001 | ACCESS DENIED | 잘못된 접근. 잘못된 옵션 값이 전달되어 동영상 재생 불가 |
| E0002 | NOT AUTHORIZED | 동영상을 재생할 권한이 없음. 잘못된 요청으로 플레이어 인증 실패 |
| E0003 | NETWORK ERROR | 네트워크 연결이 원활하지 않음. 네트워크 문제로 플레이어 인증 실패 |
| E0004 | CANNOT PLAY VIDEO | 동영상을 재생할 수 없음. 영상 재생 실패 |
| E0005 | LICENSE IS INVALID | 라이선스가 유효하지 않음. 플레이어 라이선스가 만료되어 동영상 재생 불가 |
| E0006 | LIMIT DENIED | 월 기본 제공 호출 건수를 초과. 무료 플레이어의 월 제공량을 모두 소진하여 동영상 재생 불가 |

## 전체 HTML 예제

```
<!DOCTYPE html>
<html lang="ko">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>VPE Player - 에러 대응</title>

  <!-- hls.js / dash.js를 VPE 스크립트보다 먼저 로드 -->
  <script src="https://player.vpe.naverncp.com/lib/js/hls.min.js"></script>
  <script src="https://player.vpe.naverncp.com/lib/js/dash.all.min.js"></script>
  <script src="https://player.vpe.naverncp.com/v2/ncplayer.js?access_key=YOUR_ACCESS_KEY"></script>
</head>
<body>
  <div id="video" style="max-width: 800px; margin: 0 auto;"></div>

  <div id="error-overlay" style="display:none; color:red; text-align:center; padding:20px;">
    <h2>재생 오류가 발생했습니다</h2>
    <p id="error-detail"></p>
  </div>

  <script>
    const player = new ncplayer("video", {
      playlist: [
        {
          file: "https://CDN도메인/example_video_01.mp4",
          poster: "https://CDN도메인/poster.jpg",
        },
      ],
      retry: {
        maxRetry: 5,
        interval: 3000,
      },
      override: {
        error: function(err) {
          document.getElementById("error-overlay").style.display = "block";
          document.getElementById("error-detail").textContent =
            err.errorCode + " - " + err.errorMessage;
        },
      },
    });

    player.on("error", function(err) {
      console.log("에러 발생:", err.errorCode, err.errorMessage);
    });
  </script>
</body>
</html>
```