ytdl-org/youtube-dl · error · ExtractorError

error

Error message

error

What it means

Raised by the YandexMusic base extractor's _handle_error when a downloaded JSON response is a dict with a truthy 'error' key. Yandex's API signals failures (invalid track/album IDs, expired sessions, rate limits) in that field, and its string value is raised verbatim.

Source

Thrown at youtube_dl/extractor/yandexmusic.py:26

from .common import InfoExtractor
from ..compat import compat_str
from ..utils import (
    ExtractorError,
    int_or_none,
    float_or_none,
    try_get,
)


class YandexMusicBaseIE(InfoExtractor):
    _VALID_URL_BASE = r'https?://music\.yandex\.(?P<tld>ru|kz|ua|by|com)'

    @staticmethod
    def _handle_error(response):
        if isinstance(response, dict):
            error = response.get('error')
            if error:
                raise ExtractorError(error, expected=True)
            if response.get('type') == 'captcha' or 'captcha' in response:
                YandexMusicBaseIE._raise_captcha()

    @staticmethod
    def _raise_captcha():
        raise ExtractorError(
            'YandexMusic has considered youtube-dl requests automated and '
            'asks you to solve a CAPTCHA. You can either wait for some '
            'time until unblocked and optionally use --sleep-interval '
            'in future or alternatively you can go to https://music.yandex.ru/ '
            'solve CAPTCHA, then export cookies and pass cookie file to '
            'youtube-dl with --cookies',
            expected=True)

    def _download_webpage_handle(self, *args, **kwargs):
        webpage = super(YandexMusicBaseIE, self)._download_webpage_handle(*args, **kwargs)
        if 'Нам очень жаль, но&nbsp;запросы, поступившие с&nbsp;вашего IP-адреса, похожи на&nbsp;автоматические.' in webpage:
            self._raise_captcha()

View on GitHub (pinned to 956b8c5855)

Solutions

  1. Read the forwarded error string — it comes straight from Yandex's API.
  2. Verify the track/album/playlist ID on the matching Yandex Music TLD.
  3. Pass authentication with --cookies exported from a logged-in browser session.
  4. If the error mentions automation/captcha, follow the CAPTCHA guidance (see the sibling captcha error).
Defensive patterns

Strategy: try-catch

Type guard

def yandex_response_ok(response) -> bool:
    return not (isinstance(response, dict) and response.get('error'))

Try / catch

try:
    info = ydl.extract_info(url)
except ExtractorError as e:
    if 'captcha' in str(e).lower():
        handle_captcha_flow()
    else:
        log_api_error(url, str(e))

Prevention

When it happens

Trigger: Any YandexMusic API call (download_json in extractor subclasses) whose response dict contains response['error']; _handle_error is invoked on each response before data extraction.

Common situations: Deleted tracks/albums on Yandex Music; region differences between yandex.ru/kz/ua/by/com TLDs; requests without valid cookies being rejected by the API.

Related errors

AI-assisted analysis of ytdl-org/youtube-dl@956b8c5855 (2026-08-14). Data as JSON: /api/errors/fd0bd47b62deeda4. Report an issue: GitHub.