Errors
View as MarkdownWhen a request fails, the API responds with an HTTP status code and a JSON body:
{ "error": { "code": "head_moved", "message": "The head of variation 'main' moved: it is now 4f0a1c2e-6b3d-4e59-a7c4-1d2e3f4a5b6c. Fetch it, re-apply your change on it and send the change again." } }
codeis stable: branch on it in your code.messagesays what went wrong and what to do. Its wording may change.- Every response carries a
Request-Idheader. Quote it when you report a problem.
Work that finishes in the background, such as a render or an upload, reports a failure the same way. Its error field holds { "code": "…", "message": "…" }, or null when it did not fail. Background work lists those codes.
Request errors
The Retry? column says whether sending the request again can work:
- Yes: send it again, with backoff. For a
POSTorPATCHwithout anIdempotency-Key, check first that it did not take effect (retrying). - After
Retry-After: wait the seconds in theRetry-Afterheader, then send it again. - Later: send it again once the work or state the row names has changed.
- After a fix: change the request, or what it refers to, first.
- No: the same request can't succeed.
| Status | Code | Retry? | Meaning and what to do |
|---|---|---|---|
| 400 | invalid_request |
After a fix | A field, header or query parameter is missing or invalid, or the body is not valid JSON. The message names the problem. Fix it and send again. Over MCP, a tool argument the tool does not take is refused with it too. Unknown fields nested inside an argument, such as in an edit's files, are ignored. |
| 400 | font_license_required |
After a fix | The request adds a font file without fontLicenseAccepted: true. Confirm you hold a license that allows rendering with it (Fonts) and send again with the flag. |
| 401 | unauthorized |
After a fix | The API key or MCP sign-in is missing, invalid, expired or revoked. Send a valid key as Authorization: Bearer <key> (Authentication). |
| 401 | invalid_token |
After a fix | An HLS playback link expired or is invalid. Fetch the render again for a fresh hlsUrl. |
| 402 | insufficient_render_seconds |
After a fix | There are not enough render seconds. Or the workspace has no free trial, its trial or plan has ended, or a failed payment is still unpaid 3 days after the period ended, which also refuses uploads and edits that add files. The message says which. Choose or change a plan, or update your card, in Console → This workspace → Plan & billing. |
| 402 | payment_disputed |
Later | A payment for this workspace is disputed with the card's bank. Renders, uploads and edits that add files are paused until the dispute is closed. |
| 403 | plan_limit |
After a fix | The render is longer or larger than your plan allows. Nothing was charged. Make the composition shorter or smaller. The message says whether a larger plan or sales can lift the limit. |
| 403 | plan_feature |
After a fix | Your plan does not include what you asked for: a share link, a codec other than h264, or encoding settings. Nothing was charged. Ask without it, or choose a plan that includes it. |
| 403 | storage_limit |
After a fix | Your workspace stores as much as its plan allows, counting uploads not yet completed and renders still queued or running, so the upload, the files a version adds, or the render does not fit. Delete projects or renders you no longer need, or choose a larger plan. |
| 403 | project_too_large |
After a fix | The upload, edit or ZIP import would make a version larger than your plan's project size, or the copy or variation starts from a version larger than that and than every head of its project. A ZIP is checked when it is imported; its upload is refused only when it is too large to import over any head of your workspace. Nothing changed. Remove or shrink files, or choose a larger plan: larger plans allow larger projects. A version that is already larger still renders, and an edit that does not make it larger is accepted. |
| 403 | role_not_allowed |
After a fix | MCP sign-in only: your role in the workspace can't use the API (billing members manage only plan and payment). Ask an owner or admin to change your role. |
| 403 | workspace_suspended |
After a fix | Code Artworks suspended the workspace. Its API keys, MCP sign-ins and console stop working, and queued work waits. Suspending deletes nothing, though we may delete the files of a workspace suspended for abusing free trials. Contact support to restore it. |
| 403 | email_not_verified |
After a fix | MCP sign-in only: your Code Artworks account has not confirmed its email address. Confirm it, then connect again. |
| 403 | key_cannot_revoke_keys |
No | An API key can revoke only itself, and a signed-in MCP connection only the keys its person created. Revoke other keys in the console (API keys). |
| 404 | not_found |
After a fix | The object, or one the request body names (such as a fromVersionId), doesn't exist or belongs to another workspace, or no endpoint matches the path. Check the id and path. |
| 405 | method_not_allowed |
After a fix | The endpoint does not accept that HTTP method. See the API reference. |
| 409 | head_moved |
After a fix | An edit or ZIP import sent an expectedHeadVersionId that is no longer the head of its variation (main unless it names another). Someone changed it after you read it: get the head again, re-apply your change on it and send it again. Without expectedHeadVersionId, it means other edits landed first three times in a row: send the same edit again. See edits and the head. |
| 409 | idempotency_key_in_use |
Later | A request with the same Idempotency-Key is still running. Once it has finished, send yours again with the same key (retrying safely). |
| 409 | variation_exists |
After a fix | The project already has a variation with that name. Pick another name, or use the one it has. |
| 409 | variation_limit |
After a fix | The project already has 100 variations, main included. Delete one first. |
| 409 | render_active |
After a fix | The render is still queued or running. Cancel it before deleting it. |
| 409 | renders_active |
After a fix | The project has queued or running renders. Cancel them before deleting the project. |
| 409 | render_finished |
No | The render already succeeded or failed, so it cannot be cancelled. Delete it if you no longer need it. Cancelling a render that is already cancelled is not an error: it comes back unchanged. |
| 409 | render_not_ready |
Later | The render has not succeeded. If it is still running, wait for it, then try again. If it failed or was cancelled, render the version again. |
| 409 | upload_incomplete |
After a fix | An upload the request names has not been completed. Upload its bytes (every part, for multipart) and complete it first. |
| 409 | upload_processing |
After Retry-After |
An upload the request names is still being checked. The message names each one still being checked. Wait the seconds in the Retry-After header, or get the upload with Prefer: wait=N, then try again. |
| 409 | upload_failed |
After a fix | An upload the request names failed its check. The message gives the upload's own error. After interrupted, complete the upload again. After anything else, create a new upload. |
| 409 | webhook_disabled |
After a fix | The webhook endpoint is disabled. Enable it before redelivering, testing or resending what it missed. |
| 409 | too_many_share_links |
After a fix | The project already has 50 share links. Revoke one first. |
| 408 | too_slow |
Yes | An MCP request body over 1 MB took more than two minutes to arrive. Send it again over a faster connection, or send large files through an upload. |
| 409 | api_key_limit |
After a fix | The workspace already has 25 active API keys (shown in the console, where keys are created). Revoke one first. |
| 409 | webhook_limit |
After a fix | The workspace already has 10 webhook endpoints. Delete one first. |
| 409 | upload_limit |
After a fix | The workspace already has 100 unused uploads. Use or delete some, or wait for them to expire. |
| 409 | archive_limit |
Later | 10 download archives are already waiting or building. Wait for one to finish. |
| 409 | export_limit |
Later | 10 version exports are already waiting or building. Wait for one to finish. |
| 409 | import_limit |
Later | 10 ZIP imports are already waiting or running. Wait for one to finish. |
| 413 | too_large |
After a fix | The request body is over the endpoint's limit: 64 MB for edits, renders, batch renders and MCP. Or a file is over the limit for its kind (file capabilities), or an HTML5 ad would exceed its size limit. Send large files through an upload. For an ad, render at a lower quality or shorten the video. |
| 415 | unsupported_media_type |
After a fix | The body was not sent as JSON. Add Content-Type: application/json. |
| 422 | idempotency_key_reused |
After a fix | That Idempotency-Key was used in the last 24 hours for a different request. That includes other fields or values, another render or batch, and a single render sent again as a batch (or the reverse). It also includes a batch some of whose renders you deleted. Send this request with a new key (retrying safely). |
| 422 | version_not_renderable |
After a fix | The version can't be rendered. Render refusals lists why and what to do. A render that started can fail with it too (background work). |
| 429 | rate_limited |
After Retry-After |
Too many requests (rate limits), or, in an hour, more than 10 problem reports or 20 webhook endpoints added or repointed, or more than 30 test events and redeliveries to one webhook endpoint (or any while 100 of its deliveries are waiting). Wait the seconds in the Retry-After header, then retry. Over MCP, the request limit is an HTTP 429 with a Retry-After header, before any tool runs. Those two workspace limits come back as a tool result whose text ends with the wait, such as Retry-After: 12 seconds. |
| 451 | region_unavailable |
No | The REST API and MCP are not available in the country the request comes from. Contact us if you need access from there. |
| 500 | internal_error |
Yes | Something failed on Blitframe's side. Over MCP, an unexpected failure comes back as JSON-RPC error -32603 with HTTP 500. Send the request again. If it keeps failing, report a problem with the Request-Id. |
| 503 | interrupted |
Yes | Work stopped on Blitframe's side before it finished. For example, a font took too long to convert, or a video or audio file could not be read. Send the request again. For a ZIP import, import the ZIP again. |
| 503 | backup_unavailable |
Yes | The backup image of an HTML5 ad for The Trade Desk could not be made. Retry. |
| — | invalid_arguments |
After a fix | MCP only, in a tool result with isError: the arguments do not match the tool's input. Fix the arguments and call again. |
Over MCP, any other failed tool call comes back as a tool result with isError: true, whose text starts with the code from this table, such as head_moved: … (MCP results and errors).
Render refusals
Why a request about renders is refused. A refused render or batch is not queued or charged. Uploads and variations list their refusals on their own pages.
| Request | Response | When |
|---|---|---|
| Render | 400 invalid_request |
Both projectId and versionId are sent, or neither. |
| Render or batch | 400 invalid_request |
variation is sent with versionId. |
| Render or batch | 404 not_found |
The project or version doesn't exist or belongs to another workspace, or the project has no such variation. |
| Render or batch | 400 invalid_request |
frames is missing for a frame render, or sent with mp4 or hls. Or it is not 0 ≤ start < end ≤ the frame count, or covers more than 1,000 frames. |
| Render or batch | 400 invalid_request |
audio has no path, its offsetSeconds is outside 0 to 3,600, or its path is not an audio file in the version. |
| Render or batch | 400 invalid_request |
A replacement does not fit the pinned version. Its layer is missing or of the wrong kind, or its font or path does not exist (replacements in a render, replacement details). |
| Render or batch | 400 invalid_request, or 409 upload_incomplete, upload_processing or upload_failed |
An upload a replacement names is not usable (which response when). |
| Render or batch | 400 invalid_request |
An upload is named more than once. In a batch, each upload can be named by one item only. |
| Render or batch | 400 invalid_request or 422 idempotency_key_reused |
The Idempotency-Key breaks the key rules, or was used for another request (retrying safely). |
| Batch | The item's response | One item is refused. The message starts with the item, such as renders[1]: …, and no render of the batch is queued. |
| Render or batch | 413 too_large |
The request body is over 64 MB. |
| Render or batch | 422 version_not_renderable |
The project is empty, or the version has problems. Fix the version first. |
| Render or batch | 422 version_not_renderable |
The version's files total more than 8 GB. Remove files the composition does not use. |
| Render or batch | 422 version_not_renderable |
An MP4 or HLS render is asked of an odd width or height. Make the size even, or render frames. |
| Render or batch | 422 version_not_renderable |
What the render writes alone needs more than 40 GB on the render server. For frames, render fewer. For a video, choose a lower quality or make it shorter. |
| Render or batch | 403 plan_limit |
The render is longer or larger than your plan allows. |
| Render or batch | 403 plan_feature |
A codec other than h264, or encoding settings, on a plan without advanced encoding. |
| Render or batch | 403 storage_limit |
The workspace's storage is full. |
| Render or batch | 402 insufficient_render_seconds |
Your balance is too low. Or the workspace has no trial, its trial or plan has ended, or a failed payment is still unpaid 3 days after the period ended. The message says which. A batch needs enough for all its renders. |
| Render or batch | 402 payment_disputed |
A payment for the workspace is disputed with the card's bank, even with seconds left. |
| Download archive | 400 invalid_request |
A render is a frame render, or has not succeeded. |
| Download archive | 404 not_found |
An id is not one of your renders. |
| Download archive | 409 archive_limit |
10 archives are already waiting or building. |
| Cancel | 409 render_finished |
The render already succeeded or failed. |
| Delete | 409 render_active |
The render is queued or running. Cancel it first. |
| HTML5 ad | 400 invalid_request |
A frame render, or a bad parameter. |
| HTML5 ad | 409 render_not_ready |
The render has not succeeded yet. For one that failed or was cancelled, render the version again. |
| HTML5 ad | 413 too_large |
The whole ad would be 5 MB or more. Render at a lower quality or shorten the video. |
| HTML5 ad | 503 backup_unavailable |
The backup image for The Trade Desk could not be made. Retry. |
Background work
These codes appear in the error field of a render, upload, ZIP import, download archive or version export. Some request codes above, such as invalid_request or too_large, can also appear there. Failed work is never retried for you: Retry? says whether starting it again can work.
| Code | Where | Retry? | Meaning and what to do |
|---|---|---|---|
interrupted |
Any | Yes | The work stopped on Blitframe's side, or, for a render, one of the version's files was missing from storage. Render, import, export or request the archive again. For an upload, complete it again: that checks its bytes again without resending them. If the message names a missing file, add that file again in an edit and render the new version. A render that ends interrupted is always refunded. |
check_limit |
Uploads | After a fix | Checking the upload stopped on Blitframe's side three times. Create a new upload of the file. If it keeps happening, report a problem. |
internal_error |
Any | Yes | It failed on Blitframe's side. Send it again. If it keeps failing, report a problem. A render that ends internal_error is always refunded. |
render_failed |
Renders | After a fix | The engine could not render the version. Check that the composition uses supported features. |
render_timed_out |
Renders | Yes or after a fix | The render did not finish within 30 minutes. If the message says the videos and images it converted are kept, render again: the next render goes on from there. If it names a file or a step it could not finish in time, rendering again stops there too, so do what the message says. For example, trim that video, or upload it as an 8-bit H.264 MP4 of at most 4,096 pixels, which needs no conversion. Otherwise make the composition shorter or simpler. |
stopped_by_support |
Renders | After a fix | Blitframe support stopped the render, and the message says why. Its render seconds were refunded. |
version_not_renderable |
Renders | After a fix | The render needs more than 40 GB on the render server (render workspace). Declare each image at its file's size, use fewer or shorter videos with transparency or an odd width or height, or render fewer frames or a shorter video. With replacements, it can also mean the version made for the render has problems: get the render's versionId and read them. If that versionId is still null, the replacements' files would take the version over 8 GB, so none was made: use smaller replacement files. |
| any other code | Renders | After a fix | The version failed a check when the render started. Or the version for a render's replacements could not be made, so its versionId stays null. Fix the version or the replacements, then render again. |
invalid_request |
Download archives | After a fix | A render was deleted while the archive waited, or has no video any more. Or the videos total more than 8 GB, which is checked while the archive is built. Request a new archive, split into smaller ones when it was too large. |
invalid_request |
ZIP imports | After a fix | The ZIP's upload was deleted while the import waited, or had less than an hour left when the import started. Upload the ZIP again and import it. |
Retrying
429, and5xxon aGETor on a request sent with anIdempotency-Key, are safe to retry with backoff.- Creating a project or variation, editing, importing a ZIP and rendering take an
Idempotency-Key. Send one, and a retry after a timeout or a lost response gets the first request's result instead of doing the work twice (retrying safely). A key replays for 24 hours. - Other
POSTandPATCHrequests may have taken effect before the error. Check before sending them again. - An edit that fails leaves the project unchanged, so you can send it again. Without a key, if the response never arrived, get the head first: it shows whether the edit went through. An edit retried with the same
expectedHeadVersionIdcannot apply twice. If the first one went through, the retry gets409 head_moved.