---
title: "エラー対応"
slug: "vpe-react-error-handling"
updated: 2026-09-17T09:22:05Z
published: 2026-09-17T09:22:05Z
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 | 月間の基本提供呼び出し数を超過。無料プレイヤーの月間提供量をすべて使い果たしたため、動画再生不可 |