返回与错误
响应结构、错误码,以及哪些错误值得重试。
成功响应
大多数接口会把数据包一层:
{ "success": true, "data": { } }也有一些接口直接返回裸对象。请以各接口参考页上的响应 schema 为准,下表是汇总。
| 分组 | 成功响应结构 |
|---|---|
| 评论、账号连接、数据洞察、帖子、Meta 广告、TikTok 广告 | { "success": true, "data": … } |
| 自动化 | 裸对象(没有 success / data 包装) |
| 内容 | 混合:GET/POST /videos、GET /localization、GET /tts、POST /repurpose 有包装;POST /videos/upload 和 POST /localization 是裸对象 |
| 发布 | POST /social-posts → { "success": true, "results": { … } }(定时发布时是 scheduled 相关字段);POST /social-posts/status → { "results": { … } };POST /social-posts/schedule/status → { "items": […] };POST /social-posts/schedule/cancel → { "success": true, "cancelled": … } |
错误响应
出错时返回非 2xx 状态码,JSON 里有 error 字段:
{ "error": "NOT_FOUND" }部分错误还会带上 message、field、platform、resetsAt、upgradeUrl 等字段。
请根据 error 加 HTTP 状态码分支处理,message 只用于调试。
有两个例外需要注意:
- 鉴权失败返回
{ "error": "Unauthorized" }(就是这个拼写)。 POST /api/v1/social-posts的请求校验失败时,error里是一句可读的英文(例如"tiktokConnectionIds or tiktokAccountNames required for TIKTOK"),不是错误码。请记录下来并修正请求,不要去解析它。
错误码
| 错误码 | 状态码 | 含义 | 能否重试 |
|---|---|---|---|
Unauthorized | 401 | 缺少 API Key 或 Key 无效。 | 否,修正 Key。 |
VALIDATION_FAILED | 400 | 请求体或参数不合法,field 可能指出出错字段。 | 否 |
UNSUPPORTED_PLATFORM | 400 | 该接口不支持这个连接所属的平台。 | 否 |
INVALID_URL、INVALID_VIDEO_URL、INVALID_SOURCE_URL、UNSUPPORTED_SOURCE | 400 | 请求里的某个 URL 无法使用。 | 否 |
INVALID_CRON | 400 | 自动化的定时表达式不合法。 | 否 |
ACCOUNT_UNLINKED | 401 / 409 | 该连接没有平台授权。 | 否,需要用户重新连接账号。 |
TOKEN_EXPIRED | 401 | 平台拒绝了该连接的授权。 | 否,需要用户重新授权。 |
UPGRADE_REQUIRED | 402 | 该功能需要付费套餐,upgradeUrl 指向价格页。 | 否 |
QUOTA_EXCEEDED | 402 | 套餐额度已用完。 | 额度重置或升级后再试。 |
ACCOUNT_NOT_OWNED | 403 | 请求里的连接不属于你。 | 否 |
FEATURE_DISABLED | 403 | 该功能对此账号或当前部署未开放。 | 否 |
NOT_FOUND、ACCOUNT_NOT_FOUND | 404 | 不存在,或不属于你。 | 否 |
META_ADS_NOT_CONNECTED、TIKTOK_MCP_NOT_CONNECTED、TIKTOK_MARKETING_NOT_CONNECTED | 404 | 该用户还没授权对应的广告集成。 | 否,请在控制台完成授权。 |
STRATEGY_EXISTS、STRATEGY_OWNED_BY_OTHER、HAS_RUNNING_TASKS、NOT_READY、ALREADY_DISCARDED | 409 | 与当前状态冲突(见自动化)。 | 只有 NOT_READY / HAS_RUNNING_TASKS 可以等一会儿再试。 |
TASK_NOT_FOUND | 404 | 自动化任务不存在,或不在待审核状态(confirm / reprocess / cancel)。 | 否 |
TASK_NOT_FAILED | 409 | 对没有失败的任务调用了 retry。 | 否 |
INVALID_IDEMPOTENCY_KEY | 400 | Idempotency-Key 必须是 1–200 个 [A-Za-z0-9:_.-] 字符。 | 否 |
IDEMPOTENCY_IN_PROGRESS | 409 | 相同 Key 的请求还在执行,或已结束但没有记录结果。 | 先查询状态再决定是否重试。 |
IDEMPOTENCY_KEY_REUSED | 422 | 同一个 Key 用在了不同的请求体上。 | 否,换一个新 Key。 |
RATE_LIMITED | 429 | 请求太频繁,见限流与重试。 | 是,等到 Retry-After / resetsAt 之后。 |
UPSTREAM_ERROR | 502 | 社交平台的 API 出错。 | 是,指数退避重试。 |
INTERNAL_ERROR | 500 | LumiPath 内部错误。 | 是,指数退避重试。 |
每个账号的发布结果有自己的 status 和 error,见发布指南。