Error handling

Available in Classic and VPC

It explains how to detect and handle errors that occur during playback.

Note

You can view the error codes on the Media analytics management page when subscribing to the Media Analytics service along with the Video Player Enhancement service.

Detect error events

The function calling the player can call error codes and messages when detecting the event with the player.on("error", (err) => {}) code.

Note

The error codes are sent to the error code list provided by the Video Player Enhancement service.

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

// error event data structure:
// {
//   errorCode: string | null,     // Example: "E0001", "E0004"
//   errorMessage: string | null,  // Error description
//   errorTitle: string | null,    // Error title
// }

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;
  }
});

Retry settings

You can customize the settings of maximum amount of retry attempts and maximum delay time before the player responds to an error.

Note

Added retry attempts during player initialization: Up to 3 attempts by default, with a 5-second interval
Added retry attempts for interrupted Live/VOD playback: Up to 3 attempts by default, with a 5-second interval

const player = new ncplayer("video", {
  playlist: [
    {
      file: "https://CDNdomain/example.m3u8",
      poster: "https://CDNdomain/poster.jpg",
    },
  ],
  retry: {
    maxRetry: 10,   // Maximum amount of retry attempts
    interval: 5000, // Delay time per retry (ms)
  },
});

Option	Type	Default value	Description
`retry`	Object	-	Retry settings
`retry.maxRetry`	Integer	`3`	Maximum amount of retry attempts
`retry.interval`	Integer	`5000`	Retry delay time (milliseconds)

Error interface override

You can replace the default error interface with your own code. By overriding the error interface, you can implement the error interface through the player overlay while keeping the playback paused at the last playback position.

// Video (MP4)
const player = new ncplayer("video", {
  playlist: [
    {
      file: "https://CDNdomain/example_video_01.mp4",
      poster: "https://CDNdomain/example_image_01.png",
    },
  ],
  override: {
    error: function(err) {
      console.log("player error:", err);

      // Customer error interface function implemented
      // Example: document.getElementById("error-overlay").style.display = "block";
    },
  },
});

Error code

The following are the error codes provided by Video Player Enhancement service:

Error code	Error message	Description
E0001	ACCESS DENIED	Invalid access. Video playback unavailable due to an invalid option value.
E0002	NOT AUTHORIZED	Not authorized to play this video. Player authentication failed due to an invalid request.
E0003	NETWORK ERROR	Network connection is unstable. Player authentication failed due to a network issue.
E0004	CANNOT PLAY VIDEO	Unable to play video. Video playback failed.
E0005	LICENSE IS INVALID	The license is invalid. Video playback unavailable because the player license has expired.
E0006	LIMIT DENIED	The monthly basic call count has been exceeded. Video playback unavailable because the monthly quota of the free player has been exhausted.

Full HTML example

<!DOCTYPE html>
<html lang="ko">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>VPE player - error response</title>

  <!-- Load hls.js/dash.js before the VPE script -->
  <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>A playback error has occurred</h2>
    <p id="error-detail"></p>
  </div>

  <script>
    const player = new ncplayer("video", {
      playlist: [
        {
          file: "https://CDNdomain/example_video_01.mp4",
          poster: "https://CDNdomain/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("Error occurrence:", err.errorCode, err.errorMessage);
    });
  </script>
</body>
</html>

Documentation Index

Error handling

Detect error events

Retry settings

Error interface override

Error code

Full HTML example