> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.beatapi.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server.

# 小红书接口返回 HTTP 200 却没有数据，为什么仍可能扣费？

> 排查小红书图文、视频、评论与回复动作在 HTTP 200 响应内返回的 data 业务错误与计费边界，分层区分 HTTP 461 与业务码 300011–300013，并在重试前保留 request_id。

小红书请求返回 HTTP 200 也可能带着错误。图文详情 `xiaohongshu.app_v2.get_image_note_detail`、视频详情 `xiaohongshu.app_v2.get_video_note_detail`、一级评论 `xiaohongshu.app_v2.get_note_comments` 和回复 `xiaohongshu.app_v2.get_note_sub_comments` 在目标笔记不可用或链接解析失败时，可能在 `data` 中返回「笔记不存在」「链接解析失败」等业务错误，这类响应可能按正常调用计费。HTTP 200 却没拿到笔记或评论时，先保存 `request_id`，再检查响应里的 `data`。

例如分享链接解析失败，先核对原链接和传给 `share_text` 的值。有已确认的笔记 ID 时，下一次查询改用这个 ID。要核对账单，保留请求号和实际调用时间。

## 先检查什么？

1. 保存原始响应和 `request_id`，查看网关状态，再确认 `data` 是预期笔记/评论还是错误信息。
2. 核对输入：完整链接放 `share_text`，笔记 ID 放 `note_id`；回复另传真实父 `comment_id`，三者不能互换。
3. 只是可选字段缺失时，不当作整个查询失败；只是工具预览条数少时，不当作原始结果只有几条。
4. 相同错误链接连续失败时停止，不循环尝试多个动作，也不通过反复付费请求“刷新”无效 ID。

四个动作的字段结构各不相同，不能用一条“检查 `data.items` 是否为空”的规则通吃。两个评论动作的公开合同尚未固定输出 schema；下方诊断脚本 diagnose_comment.py 使用的评论路径来自已保存的真实成功响应。面向客户的界面应概括问题并保留 request_id，不直接展示未清洗的底层错误。

## 失败不收费和这条说明矛盾吗？

Inspect 通用错误说明里的不收费规则针对平台不可达的 502 失败调用；正常响应里带业务错误是另一类情况。不要把 502 的规则概括成“只要没拿到想要的数据就免费”。对具体扣费有疑问时，保留请求 ID 与调用时间核对账单，不公开 API key。

## 如何减少无效尝试？

执行前用免费的 Inspect 核对目标动作和当前参数。已知是视频笔记就选 `xiaohongshu.app_v2.get_video_note_detail`，已知笔记 ID 就不再付费搜索。每轮先限定一页或一个对象，检查真实响应后再扩大采集范围。客户端重试不会自动免除正常调用费用。

[链接和输入选择](/zh/faq/xiaohongshu-share-links) · [评论采集流程](/zh/guides/xiaohongshu-note-comments)

来源：`data:xiaohongshu.app_v2.get_image_note_detail`、`data:xiaohongshu.app_v2.get_video_note_detail`、`data:xiaohongshu.app_v2.get_note_comments`、`data:xiaohongshu.app_v2.get_note_sub_comments` 的免费合同检查。

## 把已保存评论响应分诊，不再次发请求

把脚本保存为 diagnose_comment.py，执行 `python3 diagnose_comment.py comments.json diagnosis.json`。diagnose_comment.py 只处理直接通过 HTTP 保存的两个评论动作响应，不处理 MCP 裁剪预览。输出包含请求ID、诊断类型和条数，不复制底层错误、作者数据或请求头；脚本不重试，也不判断退款。真实成功样本已核对为 data.code=0、data.success=true、data.data.comments\[]。

评论数组为空只表示这一页没有评论，不能据此断言笔记不存在或已经采完；缺少评论数组也不等于空数组。has_more=true 时检查分页状态，不要因为当前页为空就自动重跑。

```python
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)
```

## HTTP 461 就是小红书账号被封了吗？

不一定。先看是哪条请求返回了 HTTP 461。如果是旧工具直连小红书，先暂停那批任务，到官方 App 检查账号状态。开源客户端 MediaCrawler 把 461 和 471 归到验证相关错误，仅凭 461 无法判断账号是否被永久封禁。[客户端代码](https://github.com/NanmiCoder/MediaCrawler/blob/main/media_platform/xhs/client.py) · [维护者讨论](https://github.com/NanmiCoder/MediaCrawler/issues/776)

业务同事转来一条报错时，请对方补上请求域名、HTTP 状态和发生时间，有 BeatAPI 请求编号时一并记录。用下表判断该检查平台账号、检查 BeatAPI Key，还是查看已保存的响应。

| 已有证据                                                          | 能确认什么                            | 接下来做什么                                                    |
| ------------------------------------------------------------- | -------------------------------- | --------------------------------------------------------- |
| 自己的浏览器/爬虫直连小红书返回 HTTP 461/471                                 | 这是直连小红书的 HTTP 失败，不是 BeatAPI 鉴权失败 | 暂停浏览器或爬虫的任务，通过官方 App/网站检查自己的账号，不把 Cookie 或验证令牌转交 BeatAPI。 |
| BeatAPI 返回 HTTP 401，错误为 `missing_api_key` / `invalid_api_key` | BeatAPI 鉴权失败                     | 私下检查配置的 BeatAPI 凭据；登录小红书不能修复这个错误。                         |
| BeatAPI 返回网关错误                                                | 这次请求在网关被拒绝或失败                    | 保留请求 ID、实际状态和时间，按网关错误分类，不把所有失败改称“461”。                    |
| BeatAPI 外层 HTTP 200，内部 `data` 是业务失败                           | 传输成功没有交付目标内容                     | 用对应动作的解析器检查已保存业务状态，不据此判账号被封或本次免费。                         |

报错文本里出现“461”，不等于外层 BeatAPI HTTP 状态就是 461。同样，JSON 中的 `300011` 与 HTTP 状态 `461` 是两个不同的证据字段，不能互相推出。上面的 diagnose_comment.py 只处理直接保存的 BeatAPI 评论 JSON，不处理爬虫 HTML、登录页或其他动作；爬虫 HTML 和登录页另行留档，不要塞进错误的解析器。

整理排查记录时，填写 UTC 观察时间、**不含查询参数值**的请求域名与路径、动作名、实际外层 HTTP 状态、返回的请求 ID，以及网关失败/业务失败/无法识别内容的分类。不放 API Key、Cookie、Authorization 头、签名查询串、验证 UUID 或原始个人正文。没有请求 ID 就写“未返回”，不能编造。完整原始响应私有保存供排查；写这份简要记录不会发起 API 请求，本页也不会替你发送记录。

本文链接的 BeatAPI 搜索、详情、评论动作使用你自己的 BeatAPI Bearer Key 和内容定位参数，不需要小红书登录 Cookie，所以不必把自己的浏览器会话复制进这些请求。但 BeatAPI 动作**不承诺**免疫平台限制、无限成功采集、自动重试或自动退款。暂停失败的批次，先诊断一份已有记录，再决定是否批准下一次收费。本页不提供绕过验证的步骤，也不保证升级爬虫就能恢复账号。

## 300011、300012、300013 分别是什么意思？

把 300011、300012、300013 当作已有平台或客户端记录里的业务码，不是 HTTP 状态，也不是完整官方错误码字典里的条目。每个业务码都要连同出现层级一起保留：

| 代码       | 有来源支持的解释                                                      | 不能证明什么                   |
| -------- | ------------------------------------------------------------- | ------------------------ |
| `300011` | MediaCrawler 命名为 `SECURITY_LIMIT_CODE`，按账号安全限制处理              | 永久封号、具体触发行为或确定恢复时间       |
| `300012` | MediaCrawler 命名为 `IP_ERROR_CODE`；xhs 库命名为 `IP_BLOCK`，关联网络异常提示 | 自家路由器坏了、换 IP 一定解决或应该更换代理 |
| `300013` | 一份作者主页错误跳转记录提示访问频次异常                                          | 全平台固定每秒限额、重置时间或继续重试许可    |

来源：[当前 MediaCrawler 客户端](https://github.com/NanmiCoder/MediaCrawler/blob/main/media_platform/xhs/client.py)、[xhs 库的错误定义](https://github.com/ReaJason/xhs/blob/master/xhs/exception.py)和[作者的 300013 问题记录](https://github.com/NanmiCoder/MediaCrawler/issues/522)。表中的名称是这些项目各自的解释；某个页面或客户端的记录不代表所有接口的行为，通用的“重启”提示也不是经过验证的修复步骤。

对已保存的 BeatAPI 评论响应，diagnose_comment.py 从精确的 `data.code` 路径保留整数 `business_code`，不复制原始消息。`business_code: 300013` 加上 `diagnosis: upstream_business_error` 表示这份保存的信封报告了业务码 300013；脚本不会把外层 HTTP 状态改成 300013，不发新请求，也不判断是否收费。布尔 false 和字符串 "0" 不会被当作已核实的整数成功码；非空的网关 error 优先于矛盾的 `status: succeeded` 或看似成功的评论数据。

如果代码只出现在爬虫 HTML 或跳转 URL 里，用上文的人工证据记录，不要伪造一个带 `data.code` 的 API 响应；共享记录去掉签名查询值。暂停失败的采集：自己的直连会话，通过官方界面核查账号状态；保存的 BeatAPI 请求，通过正常支持渠道排查。本页不会替你发送支持消息。固定等待时长、反复登录、轮换账号或更换代理都不是保证有效的办法。免传 Cookie 的 App 工作流不用传你自己的浏览器会话，但平台返回的业务错误照样可能出现，也不构成退款依据。

## 第三方客户端给了 300011、300012 或 300013，先看哪一层？

先保存原工具的名称、调用时间、HTTP 状态和工具实际显示的提示。账号异常、连接异常、访问频次之类的提示当作排查线索；数字代码的含义以报出代码的客户端和已确认的材料为准。网页跳转单独记录原目标和实际返回，不据此推断账号处罚。

只读公开笔记时，按[链接与详情](/zh/faq/xiaohongshu-share-links)选对应的 BeatAPI 读取动作；那里的示例用 BeatAPI Bearer 鉴权和目标笔记的链接或 ID。账户插件、爬虫和平台操作各有独立的会话和状态，遇到报错先看报错工具自己的记录。迁移时先在一份已保存的响应上验证新的字段映射和导出，再决定是否发新请求。