# 提号（tihao）数据采集 · 错误码速查

> 给 Agent 按需查阅。**核心纪律：不是所有报错都是「余额不足」。** 只有 **HTTP 402** 才提示充值；
> **401 = token 问题**（缺失/失效/类型不对），**403 = 账号禁用/无权限**，都**不是没钱**，不要引导充值。

适用范围：`tihao_api_call`（按 `channel` 走 voc-e-commerce 蒲公英网关 / voc-social 素人网关）、
以及达人直采（`live-provider.js`）。两条网关共用同一套状态码判定与话术。

## 一、总览表（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 缺失/失效/类型不对，**不是没钱、也不是关键词/类目问题**」 | 配置有效的 NewAPI `sk-` token（或回退 `r:` sessionToken）后重试 |
| 402 | `余额不足` / `额度不足` | `billing` | `needs_recharge` | 「余额不足，请充值」 | 给充值链接 `https://app.fmode.cn/dev/studio/?balance=fmodeapi`（自动打开余额弹窗） |
| 403 | `用户禁用` / `无权限` / `permission`（**不含**余额/开通关键词） | `permission` | `needs_permission` | 「账号被禁用或没有该接口权限，**≠ 余额不足**」 | 联系服务方确认账号状态/接口权限，**不要**引导充值 |
| 403 | 含 `未开通` / `没开通` / `余额` / `额度` / `insufficient` / `balance` | `billing` | `needs_recharge` | 「需开通/充值后使用」 | 给充值/开通链接 |
| 400 / 422 | `参数` / `入参` / `keyword` / `bad request` | `request` | `needs_input` | 「参数有误，**不是没数据/不是类目不支持**」 | 用 `tihao_api_doc` 核对参数后重试 |
| 5xx / 连接失败 | `fetch failed` / 超时 / `500` | `upstream` | `upstream_unstable` | 「上游接口波动」 | 稍后重试，不要误报成关键词/余额问题 |

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

```text
# 有效 sk- token（NewAPI / fmode-api）
HTTP 200  {"code":200,"data":{"code":0,"data":{"kols":[{"name":"徐卷卷","redId":"daisyue",...}]}}}

# 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}`：

1. **优先**用 NewAPI 的 `sk-` token（取值：入参 `newapiToken/fmodeApiKey` → 环境变量 `FMODE_API_KEY`/`NEWAPI_TOKEN` → `~/.claude/voc-credentials.json` 的 `fmodeApiKey`）。
2. 若 `sk-` token **鉴权失败（kind=auth / 401）** 且存在平台 `r:` sessionToken，**自动回退** sessionToken 重试一次（覆盖「服务端未迁完 / 该号未入仓 / token 未被接受」的过渡期）。
3. **402（余额不足）/ 403（无权限）不回退**——它们是终态，按上表处理。

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

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

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

> 注意第 4 与第 7 条的区别：**带「余额/开通」关键词的 403 才当充值**；**纯权限 403 一律 `permission`，不充值**。