常见问题与排障
错误码场景、授权/发布失败的处置
常见问题与排障
账号与绑定
Q：授权链接打不开/提示过期？ 授权链接 10 分钟有效。回「坐席」页重新点「绑定」获取新链接。
Q：绑定提示"该账号已绑定在其他槽位"（1006）？ 一个 TikTok 账号只能占一个坐席。要给它加第二种能力（TikTok / TikTok Shop），在它所在的那个坐席上点「追加/换绑」。
Q：提示"账号不一致"（1008）？ 同一坐席的两种能力必须是同一个 TikTok 账号（按用户名判定）。确认你这次授权登录的是同一个账号。
Q：手机授权完显示成功，但坐席页还是空的？ 桌面弹框打开期间会自动检测（约 3 秒）。没关上的话手动刷新坐席页。
视频
Q：上传报 2001？ 只支持 mp4/mov 且 ≤100MB。检查格式与大小。
Q：发布报 2005（视频已过期）？ TikTok 视频的 URL 只有 7 天有效。重新上传再发。
Q：TikTok Shop 重发同一个视频被官方拒绝（fileId 已消耗）？
TikTok Shop 规则：fileId 发布一次即作废（失败也算）。重新上传视频拿新 fileId 再发。
另外注意：fileId 与上传时的账号绑定——A 账号上传的视频只能由 A 账号发布，accountId 别传错。
Q：传了 musicId 后视频原声还在吗？
不在了。官方规则：关联 BGM 后完全覆盖视频原声（包括口播人声），不是混音。口播讲解类视频不要传 musicId。
发布
Q：发布报 1003？ 套餐到期。只读接口还能用；写操作请联系管理员续费。
Q：发布报 1005（account not bound）？
accountId 没绑定或绑错能力：TikTok 发布要用 TikTok 能力行的 businessId，TikTok Shop 发布要用 TikTok Shop 行的 creatorUserOpenId。去「坐席」页核对。
Q：TikTok 发布一直 publish_processing？ TikTok 侧审核中。「发布记录」页对进行中的记录每 10 秒自动收敛到终态，无需手点。
Q：TikTok 发布 publish_failed？ 视频内容被 TikTok 拒了（常见原因：视频太短/测试黑屏内容/违反社区规范）。换正常内容重试。
Q：TikTok Shop 发布的状态哪里看？
API：拿发布响应的 videoId 调 GET /v1/publish/tts/status?videoId=<videoId>，每 5–10 秒轮询到终态（publish_complete / publish_failed，失败原因在 failReason）。
界面：「发布记录」页对进行中的记录每 10 秒自动收敛，无需手点。
Q：TikTok Shop 发布还要不要先预审？
不强制（2026-09-13 起）：发布接口不要求预审凭证，入参全部用官方 id（fileId/accountId/productId）。
但官方规则要求违规内容不应发布，建议先 POST /v1/publish/tts/precheck 自检：轮询结果 failed（violation FAIL）就修正素材重新上传+预审，不要硬发；qualitySuggestions 只是优化建议，不影响发布。
预审配额 50 次/天/账号，耗尽报 2002，次日恢复。
Q：预审 failed 但我还是想发，平台会拦吗？
不会拦（与官方 API 行为一致）。但要想清楚：violation FAIL 是官方判定的违规内容，硬发大概率被 TikTok 拒（浪费一次性 fileId），重则影响账号健康分。建议按 violationCheckResult.issues[].suggestions 整改后重新上传。
Q：TikTok Shop 挂车视频的播放/点赞数据哪里看？
挂车视频发布后就是账号上的普通帖子（带商品锚点），数据走「数据洞察」面：haina tt insight videos --account <坐席账号>（列表按发布时间倒序，新视频在第一页，指标随行返回；返回行含 caption/create_time 供定位）。坐席需绑 TikTok 能力（洞察走 TikTok 发布体系授权）。
注意：① publish stats 是 TikTok 发布专属（记录锚定 + TikTok 发布硬校验），TikTok Shop 用不了且该命令将要废弃（1.6.x 移除）；② CLI 1.4.x 没有 insights 命令——请升级（npm i -g @hainaio/cli@latest），或直接调 GET /v1/tiktok/v1.3/business/video/list（Playground 可免安装点 Try it）。
Q：发布响应里的 quota 是什么？
官方 v202607 的创作者发布配额提示（如 3/day）。只有官方对该账号有配额限制时才会返回，没有返回不代表出错。TikTok Shop 各账号配额不同，超限后官方会报错。
Q：coverUri 和 coverTimestampMs 什么关系？
二选一：传了 coverUri（封面图 URI）就以图为准；没传就按 coverTimestampMs（毫秒）截视频帧；两个都不传，官方默认用视频首帧。
Q：TikTok 视频帖的 caption 里 @了人怎么没生效？
官方规则：@提及 仅对互关好友生效，且在 TikTok App 内显示为纯文本；#话题 同理以纯文本展示。另外 \n 换行只在 App 内且文本足够长触发截断时才生效，网页版会忽略。
Q：发布成功后视频看着比原文件糊？ 正常现象。TikTok 转码时会按播放设备和网络状况调整分辨率与比特率（官方说明），不是上传出了问题。
Q：怎么给 TikTok 视频/图片帖配背景音乐（BGM）？
先选曲再发布：haina tt music trending --account <账号> 从官方商用音乐库（CML）挑热门曲目（previewUrl 可试听），发布时把响应里的 trendingSongClipId / fullSongClipId（不是 commercialMusicId）传给 publish tt --music-id（图片帖 publish photo --music-id 同理）。
两个坑：① 音量——传了音乐没给音量时平台按 App 行为补 50/50（官方默认 0=静音），要保留视频原声（口播）需 --original-sound-volume > 0；② CML 是商用曲库，热门版权流行歌不对 Business 账号开放——要流行歌只能发草稿（--draft）后在 App 内手动加。详见 TikTok 发布全流程 · BGM。
Q：TikTok 视频能用自定义图片做封面吗？
能。两种封面方式二选一：① 视频内取帧——publish tt --thumbnail-offset <ms>（默认首帧；勿填超过视频时长的值，官方直接判失败）；② 自定义图片封面——先把图片上传到平台素材通道（haina images upload cover.jpg，或 API POST /v1/images 传 sourceUrl 取流），拿返回的 imageUrl（已过 TikTok 域名验证），发布时传 --cover-url <imageUrl>。图片要求 JPG/PNG/WebP ≤20MB。注意：传了 --cover-url 时 --thumbnail-offset 会被官方忽略。自有域名托管的图片需先在 TikTok 侧完成 URL 所有权验证。
Q：坐席页账号显示「授权已失效」？ TikTok 授权过期，或账号被 TikTok 官方限制（发布或状态查询时探测到）。在该坐席点「重新授权」重走一遍授权流程即可恢复。
接口调用
Q：401 / 1001（Token 缺失或无效）？
先确认 Header 是 Authorization: Bearer vg_live_xxx（Bearer 与 Token 之间一个空格）。在 Playground 认证框里则要只粘裸 Token，不要自己加 Bearer 前缀（细节见认证与约定）。仍失败再去「API Keys」页核对 Token 是否已被吊销。
Q：3001/3002（官方错误/超时）怎么办？
可安全重试（指数退避，最多 3 次）。TikTok Shop 发布重试前先查 /v1/publish/records——若已有该视频的发布记录，说明上次请求已到达官方，重发同 fileId 必失败，需要重新上传视频。
Q：上传大视频很慢/像「挂死」？
大概率不是挂死：上传耗时 = 你的文件传输时间（取决于上行带宽）+ 网关中转上游处理时间（网关对上游有 30s 超时兜底，超时返回 3002）。CLI 上传类超时默认 300s；用 curl 自测请把 --max-time 放宽到 300 以上。若超过 5 分钟仍无响应，再联系平台排查。
Q：挂车商品查询报 3001 invalid params / Operation Not Allowed？
挂车账号未配置「选区（selection region）」。去 TikTok Shop 卖家后台给该账号配置选区后重试即可（LOCAL 型账号的常见前置项）。showcase（橱窗）面会直接报官方明确原因。
Q：报 1005 但坐席页明明显示该账号已绑定？ 1.5.1 起这类报错会同时打出你传入的值（带引号+长度）与当前有效绑定列表——对照两者即可定位差异：最常见是复制时带入了空格/换行，或把 TikTok 的 businessId 当成了 TikTok Shop 的 creatorUserOpenId（同一账号两侧 ID 不同）。仍对不上再联系平台。
Q：哪里拿 API Key？ 后台「API Keys」页创建。明文只显示一次，请立即保存；丢了就吊销重建。
错误码总表
全部错误码与处置建议如下（与认证与约定页同源）：
| code | HTTP | 含义 | 处置建议 |
|---|---|---|---|
0 | 200 | 成功 | — |
1001 | 401 | Token 缺失/无效/已撤销 | 核对 Token（拼写/Bearer 前缀/是否已撤销）；失效或丢失则到控制台重新创建 |
1002 | 403 | 用户被禁用 | 联系管理员 |
1003 | 403 | 套餐过期（写操作被拒） | 续费后重试 |
1004 | 403 | 坐席额度不足 | 联系管理员加坐席 |
1005 | 404 | 资源不存在或不属于你 | 核对 id/账号归属（ID 口径见下） |
1006 | 409 | 该账号已绑定在其他坐席 | 追加到原坐席即可（1 账号 = 1 坐席） |
1007 | 409 | 坐席未绑定 | 先完成绑定 |
1008 | 409 | 同一坐席只能绑同一个 TikTok 账号 | 换坐席或换账号 |
2001 | 422 | 参数/文件校验失败 | 按 message 修正 |
2002 | 429 | 限流（60 次/分/token）或 TikTok Shop 预审配额耗尽 | 按 Retry-After 等待；配额次日恢复 |
2005 | 422 | 视频已过期（TikTok 视频 URL 7 天有效） | 重新上传 |
2006 | 422 | （保留码，不再返回）原 TikTok Shop 预审未通过 | 2026-09-13 起发布不强制预审，该码已下线 |
2007 | 422 | （保留码，不再返回）原缺少有效预审 | 同上 |
3001 | 502 | TikTok 官方接口返回的错误 | 读 message 官方原因；内容类违规改素材后重试，瞬时错误可重试 |
3002 | 504 | 官方接口超时 | 稍后重试 |
5000 | 500 | 内部错误 | 联系管理员 |
1005 排查序（归属类错误的最常见码）
- 先核对 ID 口径：TikTok 能力的账号 ID 是 businessId，TikTok Shop 能力是 creatorUserOpenId（两个 ID 都在坐席列表）；发布/状态查询还要分清「平台记录 id」「官方 shareId/publish_id」「TikTok item_id」。
- 核对无误仍 1005 → 停止重试（归属判定不会因重试改变），携带坐席列表输出与完整请求参数联系平台排查。
- 注意校验顺序：发布链路账号绑定校验先于视频/fileId 归属校验——先报账号错（1007）说明账号引用有问题，先报资源 1005 才轮到资源侧排查。