Перейти к навигации

Why can a Xiaohongshu HTTP 200 response contain an error and still be charged?

A Xiaohongshu request can return HTTP 200 and still carry an error. xiaohongshu.app_v2.get_image_note_detail, xiaohongshu.app_v2.get_video_note_detail, xiaohongshu.app_v2.get_note_comments and xiaohongshu.app_v2.get_note_sub_comments can return a business error inside data when the target note is unavailable or the link cannot be parsed, and these responses can still be billed at the normal rate. When an HTTP 200 response has no note or comments, save the request_id and inspect data.

For a link error, check the original URL and the value you passed as share_text. If you have a verified note ID, use the note ID for the next lookup. To reconcile a charge, keep the request ID and the call time.

What should I check first?

  1. Save the original response and the request_id. Check the gateway status, then check whether data contains the expected note or comments or an error.
  2. Verify the locator: links belong in share_text, note IDs in note_id, and a reply request needs the actual parent comment_id.
  3. Tell a missing optional field apart from a complete failure, and a small tool preview apart from a small original result.
  4. Stop repeating requests with a link that keeps failing. Do not cycle through actions or pay repeatedly to refresh an invalid ID.

The four actions do not share one result structure, so a single test for an empty data.items is wrong. The public catalog publishes no full comment schema; saved real comment responses establish the paths that diagnose_comment.py below uses. Customer-facing software should summarize the problem and keep request_id instead of displaying unfiltered platform error text.

Doesn’t the contract say failed calls are not billed?

The no-charge rule in the generic Inspect error table covers a 502 platform-unreachable failure. A normal response that carries a business error is a different case. Do not generalize the 502 rule into “any request without the desired data is free.” For a disputed charge, keep the request ID and timestamp for reconciliation, and do not share the API key.

How can I reduce invalid attempts?

Check the exact action and the current input contract with free Inspect before you run a request. When you already know the note is a video, choose xiaohongshu.app_v2.get_video_note_detail; when you already know the note ID, skip the paid search. Start with one object or one page, check the result, and only then expand collection. A client retry is not automatically exempt from normal call charges.

Choose links and identifiers · Comment collection workflow

Sources: free contract inspection of data:xiaohongshu.app_v2.get_image_note_detail, data:xiaohongshu.app_v2.get_video_note_detail, data:xiaohongshu.app_v2.get_note_comments and data:xiaohongshu.app_v2.get_note_sub_comments.

Diagnose a saved comment response without another request

Save the script below as diagnose_comment.py and run python3 diagnose_comment.py comments.json diagnosis.json. diagnose_comment.py accepts responses of the two comment actions saved directly over HTTP, not trimmed MCP previews. The output contains the request ID, the diagnosis and the row count, without raw errors, author data or request headers. The script never retries and never decides refunds. Real successful samples confirm data.code=0, data.success=true and data.data.comments[].

An empty comment array means the page has no comments; an empty array does not mean the note is absent or that collection is complete. A missing comment array is not an empty array. If has_more=true, inspect the pagination state instead of repeating an empty page.

import json
import sys
from pathlib import Path
payload = json.loads(Path(sys.argv[1]).read_text(encoding="utf-8"))
action = payload.get("action")
allowed = {"xiaohongshu.app_v2.get_note_comments", "xiaohongshu.app_v2.get_note_sub_comments"}
result = {"request_id": payload.get("request_id"), "action": action,
"retry_automatically": False, "row_count": None}
if isinstance(payload.get("data"), dict) and type(payload["data"].get("code")) is int:
result["business_code"] = payload["data"]["code"]
if action not in allowed:
raise SystemExit("Use a saved direct comment response, not an MCP preview or another action")
if payload.get("error") is not None:
result["diagnosis"] = "gateway_error_present"
elif payload.get("status") != "succeeded":
result["diagnosis"] = "gateway_not_successful"
else:
upstream = payload.get("data")
if not isinstance(upstream, dict):
result["diagnosis"] = "unexpected_upstream_shape"
elif upstream.get("success") is False or (type(upstream.get("code")) is int and upstream["code"] != 0):
result["diagnosis"] = "upstream_business_error"
elif upstream.get("success") is not True or type(upstream.get("code")) is not int or upstream["code"] != 0:
result["diagnosis"] = "success_signals_missing"
else:
page = upstream.get("data")
if not isinstance(page, dict) or not isinstance(page.get("comments"), list):
result["diagnosis"] = "expected_comment_array_missing"
else:
result["row_count"] = len(page["comments"])
result["diagnosis"] = "page_has_comments" if page["comments"] else "page_is_empty"
result["has_more"] = page.get("has_more") if type(page.get("has_more")) is bool else None
with Path(sys.argv[2]).open("x", encoding="utf-8") as output:
json.dump(result, output, ensure_ascii=False, indent=2)

Does HTTP 461 mean my Xiaohongshu account is banned?

Not necessarily. First check which request returned HTTP 461. If your old tool called Xiaohongshu directly, pause that batch and check the account in the official app. The open-source MediaCrawler client groups 461 and 471 with verification errors, and a 461 alone does not show whether the account was permanently banned. Client code · Maintainer discussion

When a colleague forwards an error, ask for the request host, the HTTP status and the time, plus the BeatAPI request ID if one exists. Use the table below to decide whether to check the platform account, review the BeatAPI Key or inspect the saved response.

Evidence you haveWhat the evidence establishesNext step
Your browser/crawler’s request to Xiaohongshu returned HTTP 461/471A direct Xiaohongshu HTTP failure, not BeatAPI authenticationPause the browser or crawler job and check your own account through the official app/site. Do not transfer the job’s Cookie or verification tokens to BeatAPI.
BeatAPI returned HTTP 401 with missing_api_key / invalid_api_keyBeatAPI authentication failedCheck the configured BeatAPI credential privately; a Xiaohongshu login does not resolve a BeatAPI authentication failure.
BeatAPI returned a gateway errorThe gateway rejected or failed the callKeep the request ID, actual status and time; use the gateway error category. Do not rename every gateway failure “461.”
HTTP 200 from BeatAPI, but nested data contains a business failureTransport success did not deliver the requested contentInspect the saved business state with the action-specific parser. Do not conclude the account is banned or that the call was free.

A “461” inside an error message is not the HTTP status of the outer BeatAPI request. Likewise, 300011 in JSON and 461 as an HTTP status are different evidence fields, and neither implies the other. diagnose_comment.py above reads direct BeatAPI comment JSON only, not crawler HTML, login pages or other actions; save crawler HTML and login pages separately instead of passing them to the wrong parser.

For an escalation note, record the UTC observation time, the request hostname and path without query values, the action name, the actual outer HTTP status, the request ID when present, and whether the result was a gateway failure, a business failure or unrecognized content. Leave out the API key, Cookie, authorization header, signed query string, verification UUID and raw personal content. If no request ID was returned, write “not returned”; never invent one. Keep the full raw response private for investigation. Writing the escalation note sends no API request, and this page sends nothing.

The linked BeatAPI search, detail and comment actions take your BeatAPI Bearer key and content locators, not your Xiaohongshu login Cookie, so you never copy your browser session into these calls. The BeatAPI actions do not promise immunity from platform restrictions, unlimited successful collection, an automatic retry or a refund. Stop a failing batch and diagnose one saved attempt before approving another charge. This page does not bypass verification and does not promise that upgrading a crawler restores an account.

What do 300011, 300012 and 300013 mean?

Treat 300011, 300012 and 300013 as observed platform or client business codes, not HTTP status codes and not entries of a complete official error dictionary. Keep each code together with the layer where the code appeared:

CodeEvidence-backed interpretationWhat the code does not prove
300011MediaCrawler names 300011 SECURITY_LIMIT_CODE and handles 300011 as an account security restrictionPermanent ban, the exact triggering behavior, or a guaranteed recovery time
300012MediaCrawler names 300012 IP_ERROR_CODE; the xhs library names 300012 IP_BLOCK and associates 300012 with a network-related messageThat your router is broken, that a new IP will resolve the block, or that changing proxies is appropriate
300013A reported author-page error redirect describes abnormal access frequencyA universal requests-per-second limit, the reset time, or permission to keep retrying

Sources: the current MediaCrawler client, the xhs library’s error definitions, and the author’s 300013 issue report. The labels in the table reflect those open-source projects’ interpretations. A report about one page or one client does not establish every endpoint’s behavior, and a generic “restart” message is not a verified repair procedure.

For a saved BeatAPI comment response, diagnose_comment.py keeps an integer business_code from the exact data.code path without copying the raw message. business_code: 300013 with diagnosis: upstream_business_error means the saved envelope reported business code 300013. diagnose_comment.py does not relabel the outer HTTP status as 300013, sends no request, and does not decide billing. Boolean false and the string "0" are not accepted as the verified integer success code. A non-null gateway error takes precedence over a contradictory status: succeeded and over comment data that looks successful.

If the code appears only inside crawler HTML or a redirect URL, use the manual evidence record above; do not invent data.code in a synthetic API response, and keep signed query values out of the shared note. Pause the failing collection. For your own direct session, check the account’s status in the official app; for a saved BeatAPI request, contact BeatAPI support through the normal support channel. This page does not send the support message for you. No fixed waiting period, repeated login, account rotation, or proxy change is a guaranteed cure. The no-cookie App workflow avoids passing your own browser session, but platform business failures still occur and do not establish a refund.

Where did a third-party 300011, 300012 or 300013 originate?

Save the tool name, the time, the HTTP status and the message the tool actually showed. Treat account, connection or frequency messages as clues, and interpret each code according to the client that reported the code and the evidence you have confirmed. For a redirect, record the original target and the response, and keep the redirect observation separate from any account decision.

To read public notes, use the matching BeatAPI link and detail workflow; the workflow’s examples use BeatAPI Bearer authentication and the note’s URL or ID. Account plugins, crawlers and platform activity have their own sessions and states, so start with the records of the tool that reported the error. When migrating, validate the new field mapping and export on one saved response before planning new requests.