错误

Reigniter API 使用标准HTTP 状态码。每个错误响应均为JSON。

误差体

大多数错误看起来像这样：

{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMITED",
  "retryAfter": 37
}

场地	永远存在	是什么
error	是的	你可以向某人展示的信息。可能会改变措辞，所以不要匹配。
code	大多数错误	一个稳定的大写代码。分支。
details	一些错误	额外的背景，比如使用 retryAfter 或使用数据。
retryAfter	一些 429	等待几秒钟后再尝试。

少数错误没有 code，如 404 Job not found 和 403 Forbidden。对这些错误的状态进行分支。

验证错误

当请求体与模式不匹配时，会 400 一个包含所有问题的 detail 字符串，列出所有问题如下 field: message：

{
  "error": "Validation failed",
  "detail": "aspect: Invalid option: expected one of \"9:16\"|\"16:9\"|\"1:1\"|\"4:5\"|\"4:3\"|\"3:4\""
}

状态代码

现状	含义	该怎么办
200	成功。
201	已创建（webhooks）。
202	接受。渲染开始了。	轮询任务或等待webhook。
400	请求被拒绝了。没有任何指控。	修正请求。不要不更改重试。
401	API 密钥丢失、无效或被吊销。	检查密钥。
402	计划、积分或使用问题。	请阅读 code。
403	账户被暂停，或者一份不属于你的工作。	联系客服，或者查看职位ID。
404	未找到。	检查ID或路径。
409	重复请求或达到限制。	请阅读 code。
413	这种渲染成本会超过每次渲染的限制。	减少场景或降低 quality。
422	渲染图没有品牌、产品或展示人来支撑。	参见 制作视频。
429	请求太多或渲染太多同时进行。	等待并重试。参见 “限制”。
500	我们这边出了点问题。	稍后再试。
502	你的简报中的规划失败了。规划积分被退还了。	重新审理，或者重新表述案情。
503	传输暂停或服务中断。没有任何费用被扣费。	稍后再试。

/v1/ 下未知路径返回 404 code: "NOT_FOUND"。

错误代码

认证与计划

代码	现状	含义
NO_API_KEY	401	没有 Authorization 首部，或者令牌不以 emp_ 开头。
INVALID_API_KEY	401	密钥未知或已被吊销。
PLAN_UPGRADE_REQUIRED	402	API 通行需要有 Agency 套餐。
ACCOUNT_SUSPENDED	403	账户被暂停了。

积分与使用

代码	现状	含义
NO_CREDITS	402	账户里已经没有积分了。
INSUFFICIENT_CREDITS	402	这个渲染图积分不够。
ABUSE_CAP_EXCEEDED	402	套餐的月度使用上限已达标。
STORAGE_FULL	402	账户的视频库已满。删除一些视频。
UPGRADE_REQUIRED	402	视频需要付费套餐。
REQUEST_COST_TOO_HIGH	413	这一次渲染的成本会超过每次渲染的限制。

有关积分和计划，请参见账户和账单。

渲染请求

代码	现状	含义
CONTENT_BLOCKED	400	简报或场景打破了内容规则。
PRODUCT_IMAGE_REQUIRED	400	该格式需要 product_image_url，或 product_enabled: false。
PRESENTER_REQUIRED	400	对话场景没有面孔。添加 avatar_preset_id，或者发送 presenter_enabled: false。
UNSUPPORTED_MODEL	400	一个场景要求渲染模型 Reigniter 无法使用。
BRAND_REQUIRED	422	有人要求烙印，但找不到。发给 brand_logo_url。
NO_ANCHOR	422	无品牌、产品照片或展示人。添加一个，或选择退出。
CANVAS_NOT_FOUND	404	这里没有引用的项目。
DUPLICATE_REQUEST	409	这 Idempotency-Key 已经用过了。没有新款被收费。
PLAN_FAILED	502	简报中的规划失败了。规划积分被退还。

对于 brief，重复的 Idempotency-Key 也可能返回为 402，并带有消息 This request was already submitted。应将其视为重复，而非积分问题。

速率与并发

代码	现状	含义
RATE_LIMITED	429	请求太多了。等 retryAfter （或 details.retryAfter）秒。
CONCURRENT_LIMIT	429	同时运行太多渲染。等一个完成。

服役经历

代码	现状	含义
USAGE_CHECK_UNAVAILABLE	503	无法检查使用情况，渲染暂停。没有收费。
DB_UNAVAILABLE	503	服务暂时中断。
FEATURE_NOT_AVAILABLE	503	目前无法提供渲染。
GLOBAL_KILL_SWITCH	503	渲染暂停了。
FEATURE_KILL_SWITCH	503	此功能暂停。
USER_KILL_SWITCH	503	该账户暂时被限制。请联系客服。

Webhook

代码	现状	含义
UNKNOWN_EVENT	400	这不是你可以订阅的活动。回复中列出了有效的活动。
URL_NOT_DELIVERABLE	400	该URL不是公开的http（s）地址。
HOOK_LIMIT	409	账户已经拥有最多的 webhook 数量。

安全重试

• 请重试 429、 500、 502 和 503 ，并带回退。不要重试其他 4xx 保持不变。
• 一定要给 POST /v1/render 发个 Idempotency-Key。
• 完全没有响应 （超时或连接中断）：用 同样 的密钥重试。如果第一个请求确实开始了渲染，重试会被拒绝，而不是启动第二次。
• 错误回复：该请求未开始渲染。修复原因后用新密钥重试，因为中途失败的请求可能已经用过了密钥。渲染积分会被退还。唯一未退还的费用是简短规划费，当计划的渲染被拒绝时（参见制作视频）。
• 如果渲染被接受（202）但后来失败，该项目的 status将 failed，error 说明原因。未完成的工作积分会退款。