Errors
Error shape, status codes and what each means.
Error shape
Every error is JSON with a machine-readable error code and a human message:
{ "error": { "code": "invalid_request", "message": "topic is required." } }Status codes
| Code | Meaning |
|---|---|
400 | Invalid request - a field is missing or malformed. |
401 | Missing or invalid API key. |
402 | Not enough credits to start the render. |
404 | Job not found (wrong id, or another account's job). |
429 | Rate limited - back off and retry. |
500 | Server error - retry; if it persists, contact support. |
Render failures
A render.failed webhook, or renderStatus: "failed" when polling, is not an HTTP error - the request succeeded but the assembly of the final video didn't.
Note the job-level status stays "completed" in that case: the scenes were generated and paid for, then refunded. Always branch on renderStatus (and a non-null finalVideoUrl), never on status alone. Credits are refunded automatically, and you can safely retry.