ytdl-org/youtube-dl · error · ExtractorError

failure

Error message

failure

What it means

Raised by the Piksel _call_api helper when the ws_<resource> JSON response contains a response.failure.reason. With fatal=True (default) it becomes an expected ExtractorError whose message is the API's failure reason verbatim ('failure' in the catalog is the variable holding that reason); with fatal=False it degrades to a warning.

Source

Thrown at youtube_dl/extractor/piksel.py:83

        }
    ]

    @staticmethod
    def _extract_url(webpage):
        mobj = re.search(
            r'<iframe[^>]+src=["\'](?P<url>(?:https?:)?//player\.piksel\.com/v/[a-z0-9]+)',
            webpage)
        if mobj:
            return mobj.group('url')

    def _call_api(self, app_token, resource, display_id, query, fatal=True):
        response = (self._download_json(
            'http://player.piksel.com/ws/ws_%s/api/%s/mode/json/apiv/5' % (resource, app_token),
            display_id, query=query, fatal=fatal) or {}).get('response')
        failure = try_get(response, lambda x: x['failure']['reason'])
        if failure:
            if fatal:
                raise ExtractorError(failure, expected=True)
            self.report_warning(failure)
        return response

    def _real_extract(self, url):
        ref_id, display_id = re.match(self._VALID_URL, url).groups()
        webpage = self._download_webpage(url, display_id)
        app_token = self._search_regex([
            r'clientAPI\s*:\s*"([^"]+)"',
            r'data-de-api-key\s*=\s*"([^"]+)"'
        ], webpage, 'app token')
        query = {'refid': ref_id, 'prefid': display_id} if ref_id else {'v': display_id}
        program = self._call_api(
            app_token, 'program', display_id, query)['WsProgramResponse']['program']
        video_id = program['uuid']
        video_data = program['asset']
        title = video_data['title']
        asset_type = dict_get(video_data, ['assetType', 'asset_type'])

View on GitHub (pinned to 956b8c5855)

Solutions

  1. Open the embedding page in a browser to check the video still plays there
  2. Update youtube-dl/yt-dlp in case the token-scraping regexes broke after a player update
  3. If the reason text indicates geo/entitlement restrictions, access via the appropriate region or account
Defensive patterns

Strategy: try-catch

Try / catch

try:
    info = ydl.extract_info(url)
except ExtractorError as e:
    if e.expected:  # failure.reason from Piksel API
        log.warning('Piksel said: %s', e)

Prevention

When it happens

Trigger: Any Piksel player API call (ws_program/api/.../mode/json/apiv/5) whose response embeds {'failure': {'reason': ...}} — e.g. expired video, invalid app_token/refid combination, or media not entitled for the domain.

Common situations: Embedded Piksel players on news sites where the video expires or is region-locked; the page's clientAPI token being rotated so the scraped token no longer authorizes; refid/prefid mismatch after site redesigns.

Related errors

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