# VOC 社交数据采集 · 错误码速查

> 给 Agent 按需查阅。**核心纪律：不是所有报错都是「余额不足」，也不是所有报错都代表「功能用不了」。** 只有 **HTTP 402** 才提示充值；
> **401 = token 问题**（缺失/失效/类型不对），**403 = 账号禁用/无权限**，都**不是没钱**，不要引导充值。
> **缺 token / 401 是可恢复的**：NewAPI 计费用的 `sk-` 就是 Claude Code 的 `ANTHROPIC_AUTH_TOKEN`（在 `~/.claude/settings.json` 的 `env` 里），取出来用 `FMODE_API_KEY=sk-…` 传入重试即可，**别当成「这个技能不能用」而放弃或去点充值**。

适用范围：`voc_api_call` / `voc_api_doc`，**三条通道同源**——社媒网关 `https://server.fmode.cn/api/voc-social/<proxyPath>`（`channel=social`，默认）、电商与创作者数据网关 `https://server.fmode.cn/api/voc-e-commerce/<proxyPath>`（`channel=ecommerce`，含京东/淘宝天猫/1688/抖音电商等电商商品 + 星图/蒲公英创作者 + 内容平台）、海外选品网关 `https://server.fmode.cn/api/voc-ecom/<proxyPath>`（`channel=overseas`，亚马逊海外选品）的鉴权、计费、错误码语义完全一致，下表对三者通用。本速查也是各 trend / 采集技能充值计费口径的**单一权威来源**，技能里只放简版摘要并指回这里。

> **首次失败 ≠ 没有该能力**：接口第一次调用失败时，**先按本表判定错误类型再决定动作，禁止立刻转 WebSearch 绕过**。`upstream_unstable`（5xx / fetch failed / 超时）→ 直接重试该接口（上游抖动，重试数次即恢复）；`needs_input` → `voc_api_doc` 核对参数后重试；`needs_token`/`needs_valid_token` → 取 `sk-` 重试。只有确认接口确实不存在该能力、且清单与 rawPath 都覆盖不了时，才考虑其它来源并如实说明。

## 一、总览表（HTTP 状态 → 含义 → 工具返回 → 给客户的话术 → Agent 动作）

| HTTP | 后端 `mess` 样例 | 判定 kind | 工具 status | 给客户 Agent 的话术 | Agent 该做什么 |
|------|------------------|-----------|-------------|----------------------|----------------|
| 200 | —（`{"code":200,"data":{...}}`） | — | `ok` | 正常返回 | 直接用 `data.result` |
| 401 | `Invalid NewAPI token` / `Missing NewAPI token` / `请输入API_KEY或用户sessionToken` / `当前用户不存在，无使用权限` | `auth` | `needs_valid_token`（无任何 token 时 `needs_token`） | 「token 缺失/失效/类型不对，**不是没钱、也不是关键词/类目问题，更不是功能用不了**」 | **先**从 `~/.claude/settings.json` 取 `env.ANTHROPIC_AUTH_TOKEN`（`sk-`），用 `FMODE_API_KEY=sk-…` 传入重试；不行再回退 `r:` sessionToken |
| 402 | `余额不足` / `额度不足` | `billing` | `needs_recharge` | 「余额不足，请充值」 | 透传工具生成的 Tokenized Balance 链接或二维码支付结果 |
| 403 | `用户禁用` / `无权限` / `permission` / `未开通` / `没开通` / `余额` / `额度` / `insufficient` / `balance` | `permission` | `needs_permission` | 「账号被禁用或没有该接口权限，**≠ 余额不足**」 | 联系服务方确认账号状态/接口权限，**不要**引导充值；只有 HTTP 402 才走充值 |
| 400 / 422 | `参数` / `入参` / `keyword` / `bad request` | `request` | `needs_input` | 「参数有误，**不是没数据/不是类目不支持**」 | 用 `voc_api_doc` 核对参数后重试 |
| 5xx / 连接失败 | `fetch failed` / 超时 / `500` | `upstream` | `upstream_unstable` | 「上游接口波动」 | 稍后重试，不要误报成关键词/余额问题 |

## 二、真实报文样例（实打抓取）

```text
# 有效 sk- token（NewAPI / fmode-api）
HTTP 200  {"code":200,"data":{"code":0,"data":{...}}}

# sk- token 无效/写错
HTTP 401  {"code":401,"mess":"Invalid NewAPI token"}

# 发的是旧版 Parse sessionToken（r:），后端已迁 NewAPI 计费
HTTP 401  {"code":401,"mess":"Missing NewAPI token"}

# 完全没带 Authorization
HTTP 401  {"code":401,"mess":"请输入API_KEY或用户sessionToken"}

# token 对应的用户不存在
HTTP 401  {"code":401,"mess":"当前用户不存在，无使用权限"}

# 余额不足（NewAPI 计费额度用尽）—— 仅此情形才引导充值
HTTP 402  {"code":402,"mess":"余额不足"}

# 用户被禁用 / 无该接口权限（区别于余额不足）
HTTP 403  {"code":403,"mess":"用户禁用或无权限"}
```

## 三、Token 优先级与回退（避开「入仓」错误）

计费已迁移到 **NewAPI（fmode-api）**，请求头统一 `Authorization: Bearer ${token}`：

> **这把 `sk-` 是什么**：它就是 **Claude Code 自己的 `ANTHROPIC_AUTH_TOKEN`**（配在 `~/.claude/settings.json` 的 `env`，`sk-` 开头，`ANTHROPIC_BASE_URL` 指向 `api.fmode.cn`）。所以 Claude Code 用户**装完即用、零额外配置**，工具会自动从 settings.json / 进程环境读到它。newapi（fmode-api）不是要单独开通的东西，就是你正在用的这把 fmode key。

1. **优先**用 NewAPI 的 `sk-` token，取值优先级：
   入参 `newapiToken/fmodeApiKey` → `.env.local` / 环境变量 `FMODE_API_KEY`/`NEWAPI_TOKEN` → `~/.claude/voc-credentials.json` 的 `fmodeApiKey` → `~/.fmode/config.json` 的 `newapiToken/fmodeApiToken` → **`~/.claude/settings.json` 的 `env.ANTHROPIC_AUTH_TOKEN`（Claude Code 默认入口）**。
   - 兼容历史：若 `VOC_TOKEN` 槽里填的就是 `sk-`，也当作 NewAPI token 使用。
   - 若工具报 `needs_token`/`needs_valid_token`：先去 `~/.claude/settings.json` 取 `env.ANTHROPIC_AUTH_TOKEN`，用 `FMODE_API_KEY=sk-…` 传入重试——**这是缺 token 的标准自救，不是去点充值**。
2. 若 `sk-` token **鉴权失败（kind=auth / 401，含「未入仓」类报错）** 且存在平台 `r:` sessionToken，**自动回退** sessionToken 重试一次。这正是规避「用户拿 token 请求时遇到入仓错误」的方式——不再因为 token 是 `sk-` 就直接拒绝。
3. **402（余额不足）/ 403（无权限）不回退**——它们是终态，按上表处理。

> **充值入口**：运行时根据当前 Session Token 生成 `https://app.fmode.cn/dev/studio/balance/?token=USER_SESSION_TOKEN`；Agent 也可按报价结果调用现有 `pay_code2` 链路返回二维码。不要固定旧 APIG URL。
>
> 运行时以工具返回的 `assistantMessage` / `nextActions` 链接为准转述，不要在话术里写死某一条。
4. 底层「未入仓」/鉴权原始报错**不甩给用户**，对外只给上表的友好提示。

## 四、判定规则摘要（`classifyApiError`）

判定顺序（命中即返回）：

1. 文案含「用户/账号信息不存在、未登录、登录失效、请输入…token、sessiontoken」→ `auth`
2. `status===401` 或文案含「invalid token / 无效token / 未授权 / unauthorized」→ `auth`
3. `status===402` 或文案含「余额不足 / 额度不足 / 未开通 / 开通…权限 / insufficient / balance / quota / payment / 充值」→ `billing`
4. `status===403` → `permission`（即使报文包含余额/开通词，也不把权限错误改判为余额不足）
5. 文案含「参数 / 入参 / keyword / 关键词 / bad request」或 `status∈{400,422}` → `request`
6. `status>=500` → `upstream`
7. `status===403` 或文案含「permission / 权限 / 无权限」→ `permission`
8. 其它 → `upstream`

> 注意：HTTP 403 统一按权限/账号状态处理，不生成充值入口；只有 HTTP 402 或服务端明确返回 402 才进入 `needs_recharge`。