NanmiCoder/MediaCrawler · critical · IPBlockError

300012

300012

Error message

Network connection error, please check network settings or restart

What it means

IPBlockError raised by XiaoHongShuClient.request when the JSON response body contains code 300012 (IP_ERROR_CODE) with the fixed message 'Network connection error, please check network settings or restart'. Despite the message, xiaohongshu emits it when the source IP is blocked/untrusted - not because of a local network outage.

Source

Thrown at media_platform/xhs/client.py:180

            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(
                f"XHS account security restriction, code: {self.SECURITY_LIMIT_CODE}"
            )

        if return_response:
            return response.text
        data: Dict = response_data if response_data is not None else response.json()
        if data["success"]:
            return data.get("data", data.get("success", {}))
        # IP_ERROR_CODE / SECURITY_LIMIT_CODE are already handled above, before return_response.
        elif data["code"] in (self.NOTE_NOT_FOUND_CODE, self.NOTE_ABNORMAL_CODE):
            raise NoteNotFoundError(f"Note not found or abnormal, code: {data['code']}")
        else:
            err_msg = data.get("msg", None) or f"{response.text}"
            raise DataFetchError(err_msg)

    @staticmethod

View on GitHub (pinned to d6f7c5bb90)

Solutions

Change the egress IP: enable ENABLE_IP_PROXY with a working proxy provider or run from a different network.
If already proxied, check the proxy pool - the provider may be returning dead/blacklisted IPs (see proxy/providers logs).
Wait some time (block is often temporary) before retrying from the same IP.
Catch IPBlockError and rotate the proxy, then retry the request.

Example fix

// before
res = await xhs_client.request("POST", uri, payload=payload)
// after
from media_platform.xhs.exception import IPBlockError
try:
    res = await xhs_client.request("POST", uri, payload=payload)
except IPBlockError:
    await xhs_client._refresh_proxy_if_expired(force=True)
    res = await xhs_client.request("POST", uri, payload=payload)

Defensive patterns

Strategy: retry

Try / catch

from media_platform.xhs.exception import IPBlockError
for attempt in range(3):
    try:
        res = await xhs_client.request(method, uri, **kwargs)
        break
    except IPBlockError:
        await xhs_client._refresh_proxy_if_expired(force=True)
        await asyncio.sleep(30 * (attempt + 1))
else:
    raise

Prevention

Run xhs crawls behind a rotating proxy pool (ENABLE_IP_PROXY).
Detect 300012 early with a canary request before a long crawl.
Reduce request volume per IP-hour to stay under block thresholds.

When it happens

Trigger: Any xhs API call from an IP on xiaohongshu's blocklist or an untrusted datacenter range; commonly appears when every request from the current IP starts returning code 300012 regardless of endpoint.

Common situations: Running the crawler from a cloud VM, an exhausted proxy pool, or after the previous IP got burned by aggressive crawling; ENABLE_IP_PROXY=false on a flagged host.

Related errors

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