error-codes.md 7.0 KB
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）的鉴权、计费、错误码语义完全一致，下表对两者通用。本速查也是各 trend / 采集技能充值计费口径的单一权威来源，技能里只放简版摘要并指回这里。
一、总览表（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 |
「余额不足，请充值」 | 给充值链接 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 |
「参数有误，不是没数据/不是类目不支持」 | 用 voc_api_doc 核对参数后重试 |
| 5xx / 连接失败 | fetch failed / 超时 / 500 |
upstream |
upstream_unstable |
「上游接口波动」 | 稍后重试，不要误报成关键词/余额问题 |
二、真实报文样例（实打抓取）
# 有效 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。
- 优先用 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 的标准自救，不是去点充值。
- 兼容历史：若
- 若
sk-token 鉴权失败（kind=auth / 401，含「未入仓」类报错） 且存在平台r:sessionToken，自动回退 sessionToken 重试一次。这正是规避「用户拿 token 请求时遇到入仓错误」的方式——不再因为 token 是sk-就直接拒绝。 - 402（余额不足）/ 403（无权限）不回退——它们是终态，按上表处理。
充值入口分两条链（按实际走哪条计费而定）：
sk-NewAPI / fmode-api 计费链（默认，绝大多数缺额场景）→https://app.fmode.cn/dev/studio/?balance=fmodeapir:会话 token 链（仅当走r:sessionToken 回退路径、该 token 余额不足时）→https://app.fmode.cn/dev/apig-pay/?apigid=Vo3ROWEvDy&fun_id=HOkkX72PMF运行时以工具返回的
assistantMessage/nextActions链接为准转述，不要在话术里写死某一条。
- 底层「未入仓」/鉴权原始报错不甩给用户，对外只给上表的友好提示。
四、判定规则摘要（classifyApiError）
判定顺序（命中即返回）：
- 文案含「用户/账号信息不存在、未登录、登录失效、请输入…token、sessiontoken」→
auth status===401或文案含「invalid token / 无效token / 未授权 / unauthorized」→authstatus===402或文案含「余额不足 / 额度不足 / 未开通 / 开通…权限 / insufficient / balance / quota / payment / 充值」→billingstatus===403且含余额/开通类关键词 →billing- 文案含「参数 / 入参 / keyword / 关键词 / bad request」或
status∈{400,422}→request status>=500→upstreamstatus===403或文案含「permission / 权限 / 无权限」→permission- 其它 →
upstream
注意第 4 与第 7 条的区别：带「余额/开通」关键词的 403 才当充值；纯权限 403 一律
permission，不充值。