跳到正文
LumiPath API

返回与错误

响应结构、错误码,以及哪些错误值得重试。

成功响应

大多数接口会把数据包一层:

{ "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"),不是错误码。请记录下来并修正请求,不要去解析它。

错误码

错误码状态码含义能否重试
Unauthorized401缺少 API Key 或 Key 无效。否,修正 Key。
VALIDATION_FAILED400请求体或参数不合法,field 可能指出出错字段。否
UNSUPPORTED_PLATFORM400该接口不支持这个连接所属的平台。否
INVALID_URL、INVALID_VIDEO_URL、INVALID_SOURCE_URL、UNSUPPORTED_SOURCE400请求里的某个 URL 无法使用。否
INVALID_CRON400自动化的定时表达式不合法。否
ACCOUNT_UNLINKED401 / 409该连接没有平台授权。否,需要用户重新连接账号。
TOKEN_EXPIRED401平台拒绝了该连接的授权。否,需要用户重新授权。
UPGRADE_REQUIRED402该功能需要付费套餐,upgradeUrl 指向价格页。否
QUOTA_EXCEEDED402套餐额度已用完。额度重置或升级后再试。
ACCOUNT_NOT_OWNED403请求里的连接不属于你。否
FEATURE_DISABLED403该功能对此账号或当前部署未开放。否
NOT_FOUND、ACCOUNT_NOT_FOUND404不存在,或不属于你。否
META_ADS_NOT_CONNECTED、TIKTOK_MCP_NOT_CONNECTED、TIKTOK_MARKETING_NOT_CONNECTED404该用户还没授权对应的广告集成。否,请在控制台完成授权。
STRATEGY_EXISTS、STRATEGY_OWNED_BY_OTHER、HAS_RUNNING_TASKS、NOT_READY、ALREADY_DISCARDED409与当前状态冲突(见自动化)。只有 NOT_READY / HAS_RUNNING_TASKS 可以等一会儿再试。
TASK_NOT_FOUND404自动化任务不存在,或不在待审核状态(confirm / reprocess / cancel)。否
TASK_NOT_FAILED409对没有失败的任务调用了 retry。否
INVALID_IDEMPOTENCY_KEY400Idempotency-Key 必须是 1–200 个 [A-Za-z0-9:_.-] 字符。否
IDEMPOTENCY_IN_PROGRESS409相同 Key 的请求还在执行,或已结束但没有记录结果。先查询状态再决定是否重试。
IDEMPOTENCY_KEY_REUSED422同一个 Key 用在了不同的请求体上。否,换一个新 Key。
RATE_LIMITED429请求太频繁,见限流与重试。是,等到 Retry-After / resetsAt 之后。
UPSTREAM_ERROR502社交平台的 API 出错。是,指数退避重试。
INTERNAL_ERROR500LumiPath 内部错误。是,指数退避重试。

每个账号的发布结果有自己的 status 和 error,见发布指南。

本页目录