NanmiCoder/MediaCrawler · critical · PlatformAccessError

300011

300011

Error message

XHS account security restriction, code: {self.SECURITY_LIMIT_CODE}

What it means

PlatformAccessError raised by XiaoHongShuClient.request when the response JSON carries code 300011 (SECURITY_LIMIT_CODE). This means the logged-in xhs account itself is under a security restriction (frequently the account is prompted to verify identity on next login), independent of IP. The message includes the code so operators can distinguish account-level from IP-level blocks.

Source

Thrown at media_platform/xhs/client.py:182

            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
    def _build_query_string(params: Dict) -> str:
        """Build URL query string with encoding matching browser behavior (commas not encoded)"""

View on GitHub (pinned to d6f7c5bb90)

Solutions

  1. Log into xiaohongshu in a browser with that account, complete any security verification prompted, then export a fresh cookie.
  2. Switch to a different (warmed) account cookie if the current one stays restricted.
  3. Reduce per-account request volume and rate; consider rotating multiple accounts.
  4. Catch PlatformAccessError, inspect the code in the message, and stop crawling with that cookie to avoid escalating the restriction.

Example fix

// before
res = await xhs_client.request("GET", uri, params=params)
// after
from media_platform.xhs.exception import PlatformAccessError
try:
    res = await xhs_client.request("GET", uri, params=params)
except PlatformAccessError as e:
    if "300011" in str(e):
        raise RuntimeError("xhs account restricted: complete verification in browser and refresh cookie")
    raise
Defensive patterns

Strategy: try-catch

Try / catch

from media_platform.xhs.exception import PlatformAccessError
try:
    res = await xhs_client.request(method, uri, **kwargs)
except PlatformAccessError as e:
    if "300011" in str(e):
        utils.logger.error("xhs account restricted - stop crawl, verify account in browser")
        raise SystemExit(2)
    raise

Prevention

When it happens

Trigger: Signed xhs API calls with a cookie whose account triggered risk control: too many requests per account, automation detected, or the account was reported/locked. Every API call returns code 300011 until the account is unlocked.

Common situations: Reusing one cookie for very long or aggressive crawls; account flagged after logging in from unusual locations (proxy IPs); sharing the crawler cookie across multiple machines.

Related errors

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