# Errors

When a request fails, the API responds with an HTTP status code and a JSON body:

```json
{ "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](/docs/blitframe/renders#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](#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](#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](/docs/blitframe/fonts#licensing)) 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](/docs/blitframe/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](/docs/blitframe/limits#plan-limits). 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](/docs/blitframe/limits#plan-limits) 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](/docs/blitframe/limits#plan-limits) 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](/docs/blitframe/limits#plan-limits), 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](/docs/blitframe/authentication)). |
| 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](/reference/blitframe). |
| 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](/docs/blitframe/variations)). 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](/docs/blitframe/projects#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](/docs/blitframe/api#retrying-safely)). |
| 409 | `variation_exists` | After a fix | The project already has a [variation](/docs/blitframe/variations#create-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](/docs/blitframe/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](/docs/blitframe/renders#waiting-for-a-result), then try again. If it failed or was cancelled, render the version again. |
| 409 | `upload_incomplete` | After a fix | An [upload](/docs/blitframe/uploads#complete-it) 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](/docs/blitframe/uploads#complete-it) 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](/docs/blitframe/uploads#complete-it) 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](/docs/blitframe/webhooks) 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](/docs/blitframe/sharing). Revoke one first. |
| 408 | `too_slow` | Yes | An [MCP](/docs/blitframe/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](/docs/blitframe/uploads). |
| 409 | `api_key_limit` | After a fix | The workspace already has 25 active [API keys](/docs/blitframe/authentication) (shown in the console, where keys are created). Revoke one first. |
| 409 | `webhook_limit` | After a fix | The workspace already has 10 [webhook](/docs/blitframe/webhooks) endpoints. Delete one first. |
| 409 | `upload_limit` | After a fix | The workspace already has 100 unused [uploads](/docs/blitframe/uploads). Use or delete some, or wait for them to expire. |
| 409 | `archive_limit` | Later | 10 [download archives](/docs/blitframe/renders#download-many-videos-as-one-zip) are already waiting or building. Wait for one to finish. |
| 409 | `export_limit` | Later | 10 [version exports](/docs/blitframe/projects#exporting-a-version) are already waiting or building. Wait for one to finish. |
| 409 | `import_limit` | Later | 10 [ZIP imports](/docs/blitframe/uploads#large-zips) 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](/docs/blitframe/uploads#file-capabilities)), or an [HTML5 ad](/docs/blitframe/renders#html5-ads) would exceed its size limit. Send large files through an [upload](/docs/blitframe/uploads). 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](/docs/blitframe/api#retrying-safely)). |
| 422 | `version_not_renderable` | After a fix | The version can't be rendered. [Render refusals](#render-refusals) lists why and what to do. A render that started can fail with it too ([background work](#background-work)). |
| 429 | `rate_limited` | After `Retry-After` | Too many requests ([rate limits](/docs/blitframe/limits#api-and-workspace)), 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](https://codeartworks.com/#contact) 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](/docs/blitframe/renders#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](/docs/blitframe/renders#html5-ads) 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](/docs/blitframe/mcp#results-and-errors)).

## Render refusals

Why a request about [renders](/docs/blitframe/renders) is refused. A refused render or batch is not queued or charged. [Uploads](/docs/blitframe/uploads#refusals) and [variations](/docs/blitframe/variations#refusals) 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](/docs/blitframe/editing#in-a-render), [replacement details](/docs/blitframe/editing#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](/docs/blitframe/editing#when-an-upload-is-refused)). |
| 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](/docs/blitframe/api#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](/docs/blitframe/limits#plan-limits). |
| 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](/docs/blitframe/renders#report-a-problem). |
| `internal_error` | Any | Yes | It failed on Blitframe's side. Send it again. If it keeps failing, [report a problem](/docs/blitframe/renders#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](/docs/blitframe/data-json-format#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](/docs/blitframe/limits#files-and-versions)). 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](/docs/blitframe/editing#in-a-render), 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](/docs/blitframe/api#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`.
