Reference

Errors & Error Codes

ytsearch.js exposes YtSearchError with a stable code field so applications can handle known failures programmatically.

class YtSearchError extends Error {
  code: YtSearchErrorCode;
  metadata?: Record<string, any>;
}

Error codes

Code	Meaning
`INVALID_QUERY`	The search query is missing, empty, or not a string.
`INVALID_TYPE`	The search type is not one of the supported SearchType values.
`INVALID_SORT`	The requested sort value is not supported.
`INVALID_LIMIT`	The requested page size is outside the function’s accepted range.
`PARSE_ERROR`	The response could not be parsed into the expected normalized structure.
`NO_RESULTS`	No matching search results were available.
`RATE_LIMIT`	The upstream service appears to have rate-limited the request.
`YOUTUBE_ERROR`	YouTube returned an error response while processing the request.
`YOUTUBE_UNAVAILABLE`	YouTube was unavailable for the requested operation.
`NETWORK_UNAVAILABLE`	A network request could not be completed.
`INVALID_PLAYLIST`	The supplied playlist identifier or playlist response was invalid.
`NO_PLAYLIST_RESULTS`	No videos were found in the requested playlist response.
`INVALID_VIDEO`	The supplied video identifier or video response was invalid.
`UNKNOWN`	An error occurred that does not match another documented code.

Treat upstream YouTube parsing and availability as external conditions. Catch YtSearchError around network-facing operations and branch on error.code where recovery behavior matters.

Next Documentation