认证与约定
Bearer Token、envelope、错误码、订阅守卫
认证与约定
Base URL
- 生产环境：
https://cli.haina.io/v1
认证
所有 /v1/* 请求需要 Bearer Token（管理后台「API Keys」页创建，明文只在创建时显示一次，请妥善保存）：
curl -H "Authorization: Bearer vg_live_xxx" https://cli.haina.io/v1/seatsPlayground 提示：
/docs/api的认证框（Bearer Token）里只粘裸 Token（vg_live_xxx），不要自己加Bearer——Scalar 会自动补前缀，重复添加会变成Bearer Bearer vg_live_xxx而被判无效（1001）。若改在 Headers 标签页手写Authorization，则必须写全Authorization: Bearer vg_live_xxx。
Token 与账号绑定：套餐到期后写操作（上传/发布）会被拒（1003），只读接口不受影响。Token 可随时在后台撤销（吊销即生效）。
统一响应信封
所有端点返回统一结构：
{ "code": 0, "message": "ok", "data": { } }code = 0：成功，data为业务数据code ≠ 0：失败，message为原因；HTTP 状态码与 code 对应（见错误码表）
即使官方 TikTok 侧失败，HTTP 也可能是 200/4xx——永远以
code为准。
错误码
| 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 才轮到资源侧排查。
限流
- 限制：60 次/分钟/token（令牌桶）
- 超限返回：HTTP
429+code 2002+Retry-After响应头 - 处置：按
Retry-After等待后重试，退避至多 3 次
重试建议
3002（官方超时）与3001中的瞬时错误：可安全重试（指数退避，最多 3 次）；3001若 message 指明内容类违规，需改素材后再试（盲重试只会再次失败）- 发布类接口重试前注意：TikTok Shop 发布的
fileId是一次性消耗品——若发布请求已到达官方，重发同一fileId会被拒；先查/v1/publish/records确认上次的发布状态 4xx类错误码（1001-2007）：不要盲重试，先修参数