tihao-ai/claude-code-tihao-sourcing/skills/tihao/references/error-codes.md

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

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

# 有效 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，不充值。