---
title: "에러 대응"
slug: "vpe-react-error-handling"
updated: 2026-09-17T09:08:03Z
published: 2026-09-17T09:08:03Z
canonical: "guide.ncloud-docs.com/vpe-react-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 서비스에서 제공하는 에러 코드 목록으로 전달됩니다.

```
import Hls from "hls.js";
import dashjs from "dashjs";
import { VpePlayer } from "@sgrsoft/vpe-react-sdk";

// onEvent에 전달되는 error 이벤트 객체 구조:
// {
//   type: "error",
//   state: PlayerStateSnapshot,      // 현재 플레이어 상태
//   prevState?: PlayerStateSnapshot,
//   data: {
//     errorCode: string | null,      // 예: "E0001", "E0004"
//     errorMessage: string | null,   // 에러 설명
//     errorTitle: string | null,     // 에러 제목
//   }
// }

export function App() {
  return (
    <VpePlayer
      accessKey="YOUR_ACCESS_KEY"
      hls={Hls}
      dashjs={dashjs}
      platform="pub"
      options={{
        playlist: [
          {
            file: "https://example.com/myVideo.mp4",
            poster: "https://example.com/myVideoThumb.png",
          },
        ],
      }}
      onEvent={(event) => {
        if (event.type === "error") {
          const { errorCode, errorMessage, errorTitle } = event.data;
          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초 간격

```
import Hls from "hls.js";
import dashjs from "dashjs";
import { VpePlayer } from "@sgrsoft/vpe-react-sdk";

export function App() {
  return (
    <VpePlayer
      accessKey="YOUR_ACCESS_KEY"
      hls={Hls}
      dashjs={dashjs}
      platform="pub"
      options={{
        playlist: [
          {
            file: "https://dobdd7vj3864.edge.naverncp.com/hls/47NWZgkwsKFkPIU1tix9Zw__/endpoint/sample/example.mp4.smil/master.m3u8",
            poster: "https://2ardrvaj2252.edge.naverncp.com/endpoint/sample/221027_NAVER_Cloud_intro_Long_ver_01.jpg",
          },
        ],
        retry: {
          maxRetry: 10,   // 최대 재시도 횟수
          interval: 5000, // 재시도 간 지연 시간 (ms)
        },
      }}
    />
  );
}
```

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

## 에러 화면 재정의

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

```
import Hls from "hls.js";
import dashjs from "dashjs";
import { VpePlayer } from "@sgrsoft/vpe-react-sdk";

// 동영상(MP4)
export function App() {
  return (
    <VpePlayer
      accessKey="YOUR_ACCESS_KEY"
      hls={Hls}
      dashjs={dashjs}
      platform="pub"
      options={{
        playlist: [
          {
            file: "https://CDN도메인/example_video_01.mp4",
            poster: "https://CDN도메인/example_image_01.png",
          },
        ],
        override: {
          error(err) {
            console.log("player error :", err);
            // 고객사 에러 화면 기능 구현
          },
        },
      }}
    />
  );
}
```

## 에러 화면 커스터마이징

참고

- `errorOverride`는 VpePlayer props로 전달하며, 에러 발생 시 플레이어 내부에 커스텀 React UI를 직접 렌더링합니다.
- `override.error`는 options 내부에 설정하는 콜백 함수로, 에러 정보를 받아 외부 로직(로깅, 별도 DOM 조작 등)을 실행합니다.

참고

유료 티어(`isPaidTier`)에서만 동작합니다.

### 타입 정의

```
errorOverride?: ReactNode | ComponentType<PlayerErrorInfo> | ((info: PlayerErrorInfo) => ReactNode);

type PlayerErrorInfo = {
  errorCode: string | null;
  errorMessage: string | null;
  errorTitle: string | null;
};
```

### 1. 렌더 함수 (가장 일반적)

에러 정보를 받아 동적으로 UI를 렌더링합니다. 에러 코드별로 다른 메시지를 표시할 때 유용합니다.

```
<VpePlayer
  accessKey="YOUR_ACCESS_KEY"
  hls={Hls}
  options={{
    playlist: [{ file: "https://CDN_DOMAIN/example.m3u8" }],
  }}
  errorOverride={(info) => (
    <div style={{
      display: "flex",
      width: "100%",
      height: "100%",
      backgroundColor: "#000",
      color: "#fff",
      justifyContent: "center",
      alignItems: "center",
    }}>
      <div>ERROR {info.errorCode}</div>
    </div>
  )}
/>
```

### 2. React 컴포넌트

별도의 에러 컴포넌트를 정의하고 전달합니다. `PlayerErrorInfo`가 props로 전달됩니다.

```
function CustomError({ errorCode, errorMessage }: PlayerErrorInfo) {
  return <div>에러: {errorCode} - {errorMessage}</div>;
}

<VpePlayer
  accessKey="YOUR_ACCESS_KEY"
  hls={Hls}
  options={{
    playlist: [{ file: "https://CDN_DOMAIN/example.m3u8" }],
  }}
  errorOverride={CustomError}
/>
```

### 3. ReactNode (고정 UI)

에러 코드와 관계없이 동일한 고정 UI를 표시합니다.

```
<VpePlayer
  accessKey="YOUR_ACCESS_KEY"
  hls={Hls}
  options={{
    playlist: [{ file: "https://CDN_DOMAIN/example.m3u8" }],
  }}
  errorOverride={<div>재생할 수 없습니다</div>}
/>
```

## 에러 코드

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

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