Home Explore Help
Sign In
18307996893
/
openclaw-voc-skill
2
2
Fork 0
Files Issues 0 Pull Requests 0 Wiki
Branch: master
Branches Tags
openclaw-voc-sk...
/
claude-code
/
claude-code-voc-intelligence
/
skills
/
voc-api-catalog
/
references
/
error-codes.md

error-codes.md 7.5 KB
Permalink History Raw

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 「上游接口波动」 稍后重试，不要误报成关键词/余额问题

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

# 有效 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 链接为准转述，不要在话术里写死某一条。

  1. 底层「未入仓」/鉴权原始报错不甩给用户，对外只给上表的友好提示。

四、判定规则摘要（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。