Handling errors — just-yt

A request can fail even when your code is correct. A video may be deleted, a caption track may not exist, the network may time out, or YouTube may change an undocumented response. Good error handling tells these situations apart.

Start with one try and catch

JavaScript sends a rejected Promise to catch:

try {
  const transcript = await yt.transcript(videoId);
  console.log(transcript.data);
} catch (error) {
  console.error('Could not read the transcript', error);
}

That is enough for a small script. An application often needs a more specific response, so just-yt exports tagged error classes.

Match the errors you can handle

import {
  ExtractionError,
  NetworkError,
  NotFoundError,
  UnavailableError,
} from 'just-yt';

try {
  return await yt.transcript(videoId, { language: 'en' });
} catch (error) {
  if (error instanceof NotFoundError) {
    return null;
  }

  if (error instanceof UnavailableError) {
    console.warn(error.status, error.reason);
    return null;
  }

  if (error instanceof NetworkError) {
    console.error('Network request failed:', error.url);
  }

  if (error instanceof ExtractionError) {
    console.error('Response changed near:', error.path);
  }

  throw error;
}

Only return a fallback when it makes sense for your program. The final throw error preserves failures this function does not know how to handle.

What the tags mean

Error	Meaning	A common response
`NotFoundError`	The requested ID or transcript track was not found.	Show “not found” or skip the item.
`UnavailableError`	A video exists but YouTube will not serve it to this anonymous client.	Show the supplied reason when appropriate.
`NetworkError`	A request could not reach YouTube or its body could not be read.	Retry later or report temporary failure.
`InnertubeError`	YouTube returned a non-success HTTP status.	Log the endpoint and status.
`ExtractionError`	The response shape did not match what this SDK understands.	Report it as possible parser drift.
`SessionError`	The shared session could not be established.	Check configuration and upstream access.

Bulk methods capture item failures

videos(), channels(), and transcripts() return one result for every input. One bad target does not reject or cancel the rest:

const results = await yt.videos(videoIds);

for (const result of results) {
  if (result.ok) {
    console.log(result.value.title);
    // → 'Me at the zoo', …
  } else {
    console.warn(result.target, result.error._tag);
    // → 'aaaaaaaaaaa' 'UnavailableError'
  }
}

The overall call can still reject when shared infrastructure, such as session creation, cannot run. This is the difference between “one item failed” and “the job could not start.”