What causes "API returned fail" in soimort/you-get?

Re-fetch the video page fresh each run so flashvars-derived tokens are current — never cache IService/uuid/other across sessions.

soimort/you-get · error · Exception

API returned fail

Error message

API returned fail

What it means

Raised as plain Exception in ICousesExactor.api_req (src/you_get/extractors/icourses.py:226). The player's XML API is queried for stream metadata; the <result> element's status attribute must be 'success'. Anything else (error, denied) aborts extraction.

Source

Thrown at src/you_get/extractors/icourses.py:226

        if hit is None:
            raise Exception('Cannot find flashvars')
        flashvar_str = hit.group(1)

        uuid = re.search(r'uuid\s*:\s*\"?(\w+)\"?', flashvar_str).group(1)
        other = re.search(r'other\s*:\s*"(.*?)"', flashvar_str).group(1)
        isvc = re.search(r'IService\s*:\s*\'(.+?)\'', flashvar_str).group(1)

        player_time_patt = r'MPlayer.swf\?v\=(\d+)'
        player_time = re.search(player_time_patt, self.page).group(1)

        self.flashvars = dict(IService=isvc, uuid=uuid, other=other, v=player_time)

    def api_req(self, url):
        xml_str = get_content(url)
        dom = parseString(xml_str)
        status = dom.getElementsByTagName('result')[0].getAttribute('status')
        if status != 'success':
            raise Exception('API returned fail')

        api_res = {}
        meta = dom.getElementsByTagName('metadata')
        for m in meta:
            key = m.getAttribute('name')
            val = m.firstChild.nodeValue
            api_res[key] = val
        self.api_data = api_res

    def basic_extract(self):
        self.get_title()
        self.get_flashvars()
        api_req_url = '{}?{}'.format(self.flashvars['IService'], parse.urlencode(self.flashvars))
        self.api_req(api_req_url)

    def do_extract(self, received=0):
        self.basic_extract()
        return self.generate_url(received)

View on GitHub (pinned to 049548f3f3)

Solutions

Re-fetch the video page fresh each run so flashvars-derived tokens are current — never cache IService/uuid/other across sessions.
Log xml_str to see the actual status/error the API returns and adjust the request accordingly.
If the XML schema changed, update api_req's parsing (or upgrade you-get).

Defensive patterns

Strategy: try-catch

Try / catch

try:
    icourses_download(url, output_dir)
except Exception as e:
    if str(e) == 'API returned fail':
        icourses_download(url, output_dir)  # exactly once: refresh page -> new tokens
    else:
        raise

Prevention

Always fetch the video page fresh so flashvars tokens (uuid/other/IService) are current.
Log the API XML body when status != success to distinguish token expiry from schema change.

When it happens

Trigger: api_req() fetches an API URL built from flashvars (IService endpoint with uuid/other), parses it with minidom, and dom.getElementsByTagName('result')[0].getAttribute('status') != 'success'. Happens when uuid/other tokens are stale or wrongly parsed, the API rejects the request, or icourses changed the response schema (also fails with IndexError if <result> disappears).

Common situations: Expired per-session tokens reused by long-running scripts; flashvars parsing producing truncated values; API contract change after site maintenance.

Related errors

AI-assisted analysis of soimort/you-get@049548f3f3 (2026-08-15). Data as JSON: /api/errors/742eceeb6d7ddbf2. Report an issue: GitHub.