CAPTCHA appeared, request failed, Verifytype: {verify_type},

Error message

CAPTCHA appeared, request failed, Verifytype: {verify_type}, Verifyuuid: {verify_uuid}, Response: {response}

What it means

Raised by XiaoHongShuClient.request when xiaohongshu returns HTTP 471 or 461 - their CAPTCHA/verification challenge statuses. The response headers carry Verifytype and Verifyuuid identifying the challenge. The code deliberately raises a bare Exception (comment: 'someday someone maybe will bypass captcha'), i.e. there is no automated solving path.

Source

Thrown at media_platform/xhs/client.py:164

        await self._refresh_proxy_if_expired()

        # return response.text
        return_response = kwargs.pop("return_response", False)
        async with make_async_client(proxy=self.proxy) as client:
            response = await client.request(method, url, timeout=self.timeout, **kwargs)

        if response.status_code in {401, 403, 429}:
            raise PlatformAccessError(
                f"XHS request blocked with HTTP {response.status_code}"
            )

        if response.status_code == 471 or response.status_code == 461:
            # someday someone maybe will bypass captcha
            verify_type = response.headers["Verifytype"]
            verify_uuid = response.headers["Verifyuuid"]
            msg = f"CAPTCHA appeared, request failed, Verifytype: {verify_type}, Verifyuuid: {verify_uuid}, Response: {response}"
            utils.logger.error(msg)
            raise Exception(msg)

        response_data: Optional[Dict] = None
        try:
            candidate_data = response.json()
            if isinstance(candidate_data, dict):
                response_data = candidate_data
        except (TypeError, ValueError):
            pass

        response_code = (
            str(response_data.get("code"))
            if response_data is not None and response_data.get("code") is not None
            else ""
        )
        if response_code == str(self.IP_ERROR_CODE):
            raise IPBlockError(self.IP_ERROR_STR)
        if response_code == str(self.SECURITY_LIMIT_CODE):
            raise PlatformAccessError(

View on GitHub (pinned to d6f7c5bb90)

Solutions

Open the same URL in a real browser with the same cookie, complete the CAPTCHA, then re-export the cookie into config.
Rotate to a cleaner proxy IP (or enable ENABLE_IP_PROXY with a residential provider) before retrying.
Slow the crawl: increase delays between requests and reduce concurrency.
Log into an xhs account (cookie login) so requests carry an established session instead of anonymous ones.

Example fix

// before
# no special handling; Exception propagates and kills the task
// after
try:
    data = await xhs_client.get(uri, params=params)
except Exception as e:
    if "CAPTCHA appeared" in str(e):
        await proxy_pool.rotate()  # or signal operator to solve manually
        await asyncio.sleep(300)
    raise

Defensive patterns

Strategy: fallback

Try / catch

try:
    data = await xhs_client.request(method, uri, **kwargs)
except Exception as e:
    if "CAPTCHA appeared" not in str(e):
        raise
    utils.logger.warning("xhs captcha - rotating IP and pausing")
    await xhs_client._refresh_proxy_if_expired(force=True)
    await asyncio.sleep(600)

Prevention

Use warmed logged-in cookies instead of anonymous sessions.
Prefer residential proxies over datacenter IPs.
Pace requests with jitter; avoid bursts after run start.
There is no built-in captcha solving - plan manual intervention or IP rotation.

When it happens

Trigger: Any xhs API call where risk control decides a human check is needed: new IP with no cookie history, high request velocity, or crawler-fingerprint detection. Verifytype/Verifyuuid headers are present on the 471/461 response.

Common situations: Datacenter/proxy IP flagged by xiaohongshu; crawling without a logged-in cookie; bursty scraping patterns right after starting a run.

Related errors

AI-assisted analysis of NanmiCoder/MediaCrawler@d6f7c5bb90 (2026-08-15). Data as JSON: /api/errors/9c87d2ac7be45159. Report an issue: GitHub.