ytdl-org/youtube-dl · error · ExtractorError

error['error_description']

Error message

error['error_description']

What it means

Raised by the Atresplayer error handler when a download fails with an HTTP error whose status code matches the expected code and the response body parses as JSON containing error_description. If the error field equals 'required_registered', the extractor instead raises a login-required error before this line. Marked expected=True.

Source

Thrown at youtube_dl/extractor/atresplayer.py:52

            'url': 'https://www.atresplayer.com/lasexta/programas/el-club-de-la-comedia/temporada-4/capitulo-10-especial-solidario-nochebuena_5ad08edf986b2855ed47adc4/',
            'only_matching': True,
        },
        {
            'url': 'https://www.atresplayer.com/antena3/series/el-secreto-de-puente-viejo/el-chico-de-los-tres-lunares/capitulo-977-29-12-14_5ad51046986b2886722ccdea/',
            'only_matching': True,
        },
    ]
    _API_BASE = 'https://api.atresplayer.com/'

    def _real_initialize(self):
        self._login()

    def _handle_error(self, e, code):
        if isinstance(e.cause, compat_HTTPError) and e.cause.code == code:
            error = self._parse_json(e.cause.read(), None)
            if error.get('error') == 'required_registered':
                self.raise_login_required()
            raise ExtractorError(error['error_description'], expected=True)
        raise

    def _login(self):
        username, password = self._get_login_info()
        if username is None:
            return

        self._request_webpage(
            self._API_BASE + 'login', None, 'Downloading login page')

        try:
            target_url = self._download_json(
                'https://account.atresmedia.com/api/login', None,
                'Logging in', headers={
                    'Content-Type': 'application/x-www-form-urlencoded'
                }, data=urlencode_postdata({
                    'username': username,
                    'password': password,

View on GitHub (pinned to 956b8c5855)

Solutions

  1. Read the embedded error_description: 'required_registered' → log in; 'required_premium' → upgrade; geolocation → use a Spain IP
  2. Supply --username/--password of an account entitled to the content
  3. If you get a KeyError on error_description, the API error shape changed — report upstream

Example fix

# before
youtube-dl 'https://www.atresplayer.com/series/premium-show/'

# after
youtube-dl --username user@example.com --password pass 'https://www.atresplayer.com/series/premium-show/'  # entitled account + Spain IP
Defensive patterns

Strategy: try-catch

Try / catch

try:
    ydl.extract_info(url)
except (ExtractorError, KeyError) as e:
    msg = str(e)
    if 'required_premium' in msg:
        requeue_with_premium_account(url)
    elif 'geoloc' in msg.lower() or 'geo' in msg.lower():
        requeue_with_region(url, 'ES')
    else:
        log_atresplayer_api_error(url, msg)

Prevention

When it happens

Trigger: API request to api.atresplayer.com returning an HTTPError whose body JSON has error_description; e.g. 403 for premium-only content without a Premium subscription, or expiredNamac / geolocation errors; _handle_error(e, 403) or 400 call sites in login and extraction.

Common situations: Non-Premium account hitting Premium content; geoblocking outside Spain; expired session tokens requiring re-login; API schema change dropping error_description (which would then raise KeyError).

Related errors

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