Errors

The Reignitor API uses standard HTTP status codes. Every error response is JSON.

Error body

Most errors look like this:

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

Field	Always present	What it is
`error`	Yes	A message you can show to a person. It may change wording, so do not match on it.
`code`	Most errors	A stable, upper-case code. Branch on this.
`details`	Some errors	Extra context, for example `retryAfter` or usage figures.
`retryAfter`	Some `429`s	Seconds to wait before retrying.

A few errors have no code, such as 404 Job not found and 403 Forbidden. Branch on the status for those.

Validation errors

When the request body does not match the schema, you get 400 with a detail string that lists every problem as field: message:

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

Status codes

Status	Meaning	What to do
`200`	Success.
`201`	Created (webhooks).
`202`	Accepted. The render has started.	Poll the job or wait for the webhook.
`400`	The request was refused. Nothing was charged.	Fix the request. Do not retry unchanged.
`401`	Missing, invalid or revoked API key.	Check the key.
`402`	Plan, credit or usage problem.	Read `code`.
`403`	Suspended account, or a job that is not yours.	Contact support, or check the job ID.
`404`	Not found.	Check the ID or path.
`409`	Duplicate request or limit reached.	Read `code`.
`413`	This render would cost more than the per-render limit.	Use fewer scenes or a lower `quality`.
`422`	The render has no brand, product or presenter to anchor it.	See Making videos.
`429`	Too many requests or too many renders at once.	Wait and retry. See Limits.
`500`	Something went wrong on our side.	Retry later.
`502`	Planning from your brief failed. Planning credits were refunded.	Retry, or reword the brief.
`503`	Rendering is paused or a service is down. Nothing was charged.	Retry later.

An unknown path under /v1/ returns 404 with code: "NOT_FOUND".

Error codes

Authentication and plan

Code	Status	Meaning
`NO_API_KEY`	401	No `Authorization` header, or the token does not start with `emp_`.
`INVALID_API_KEY`	401	The key is unknown or revoked.
`PLAN_UPGRADE_REQUIRED`	402	API access needs the Agency plan.
`ACCOUNT_SUSPENDED`	403	The account is suspended.

Credits and usage

Code	Status	Meaning
`NO_CREDITS`	402	The account has no credits left.
`INSUFFICIENT_CREDITS`	402	Not enough credits for this render.
`ABUSE_CAP_EXCEEDED`	402	The monthly usage limit for the plan is reached.
`STORAGE_FULL`	402	The account’s video library is full. Remove some videos.
`UPGRADE_REQUIRED`	402	Video needs a paid plan.
`REQUEST_COST_TOO_HIGH`	413	This one render would cost more than the per-render limit.

See Account and billing for credits and plans.

Render requests

Code	Status	Meaning
`CONTENT_BLOCKED`	400	The brief or a scene breaks the content rules.
`PRODUCT_IMAGE_REQUIRED`	400	This format needs `product_image_url`, or `product_enabled: false`.
`PRESENTER_REQUIRED`	400	A talking scene has no face. Add `avatar_preset_id`, or send `presenter_enabled: false`.
`UNSUPPORTED_MODEL`	400	A scene asked for a render model Reignitor cannot use.
`BRAND_REQUIRED`	422	A brand was asked for but none could be found. Send `brand_logo_url`.
`NO_ANCHOR`	422	No brand, product photo or presenter. Add one, or opt out.
`CANVAS_NOT_FOUND`	404	A referenced project is not on this account.
`DUPLICATE_REQUEST`	409	This `Idempotency-Key` was already used. Nothing new was charged.
`PLAN_FAILED`	502	Planning from the brief failed. Planning credits were refunded.

With a brief, a repeated Idempotency-Key can also come back as 402 with the message This request was already submitted. Treat it as a duplicate, not as a credit problem.

Rate and concurrency

Code	Status	Meaning
`RATE_LIMITED`	429	Too many requests. Wait `retryAfter` (or `details.retryAfter`) seconds.
`CONCURRENT_LIMIT`	429	Too many renders running at once. Wait for one to finish.

Service

Code	Status	Meaning
`USAGE_CHECK_UNAVAILABLE`	503	Usage could not be checked, so rendering is paused. Nothing was charged.
`DB_UNAVAILABLE`	503	A service is briefly unavailable.
`FEATURE_NOT_AVAILABLE`	503	Rendering is not available right now.
`GLOBAL_KILL_SWITCH`	503	Rendering is paused for everyone.
`FEATURE_KILL_SWITCH`	503	This feature is paused.
`USER_KILL_SWITCH`	503	This account is temporarily restricted. Contact support.

Webhooks

Code	Status	Meaning
`UNKNOWN_EVENT`	400	Not an event you can subscribe to. The response lists the valid ones.
`URL_NOT_DELIVERABLE`	400	The URL is not a public http(s) address.
`HOOK_LIMIT`	409	The account already has the maximum number of webhooks.

Retrying safely

Retry 429, 500, 502 and 503 with backoff. Do not retry other 4xx unchanged.
Always send an Idempotency-Key on POST /v1/render.
No response at all (a timeout or a dropped connection): retry with the same key. If the first request did start a render, the retry is refused instead of starting a second one.
An error response: no render was started for that request. Fix the cause, then retry with a new key, because a request that failed part-way may already have used its key. Render credits are refunded. The one charge that is not refunded is brief planning, when the planned render is then refused (see Making videos).
If a render was accepted (202) and later fails, the job’s status becomes failed and error says why. Credits for work that did not happen are refunded.