When 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." } }
  • code is stable: branch on it in your code.
  • message says what went wrong and what to do. Its wording may change.
  • Every response carries a Request-Id header. 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 POST or PATCH without an Idempotency-Key, check first that it did not take effect (retrying).
  • After Retry-After: wait the seconds in the Retry-After header, 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, and 5xx on a GET or on a request sent with an Idempotency-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 POST and PATCH requests 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 expectedHeadVersionId cannot apply twice. If the first one went through, the retry gets 409 head_moved.