Archived docs Get your API Key
Get started
Tutorials
Guides
Reference
Help for coding agents
🤖 AI Assistant

Errors

The API surfaces errors in two places:

  1. HTTP responses — synchronous endpoint errors (validation, auth, quota). The response body is { "success": false, "message": "…" } with an HTTP status code in the 4xx–5xx range.
  2. Render status — asynchronous errors discovered while a render is being produced. The render completes with movie.status = "error" and movie.message describing what failed. The HTTP status of GET /v2/movies is still 200.

All error messages are short, descriptive strings. They are not stable identifiers — match on HTTP status and on the endpoint plus message family rather than on exact text.

HTTP status code summary

Status Meaning
200 Request accepted. For GET /v2/movies, also check movie.status.
400 Validation error, invalid or missing API key, or insufficient credits.
401 Quota / plan limit error.
403 Authorisation error (role, blocked storage, invalid admin token).
404 Resource (template, movie, file) not found.
405 HTTP method not supported on this endpoint.
409 Conflict (duplicate filename on upload, etc.).
413 Payload too large (media upload > 500 MB).
500 Internal error.

Authentication errors

Returned when the request lacks a valid API key or is using one without sufficient permissions. Note that an invalid or missing API key returns HTTP 400, not 401.

Status Message Endpoint
400 Error: API Key not provided All endpoints
400 Error: Invalid API Key All endpoints
403 Insufficient permissions /v2/templates, /v2/media, POST /v2/movies (admin endpoints)
403 Invalid token Admin-only query parameters

To resolve: confirm the x-api-key header is present and that the key has the right role for the action — Render to render videos, Editor to create / edit templates, Manager to manage Connections. See API keys → Permission roles.

Quota and plan errors

Returned when the account has exhausted its plan allowance.

Status Message Endpoint
401 You exceeded the quota of movies in your plan. Please upgrade your plan to continue. POST /v2/movies
401 You exceeded the quota of drafts in your plan. Please upgrade your plan to continue. POST /v2/movies
401 Movie is larger ({w}x{h}) than your plan allowance ({w}x{h}) POST /v2/movies
400 Insufficient credits Render submission paths
403 Storage is blocked. Add credits to continue uploading. POST /v2/media/file

To resolve: top up credits or upgrade the plan. See Credits & limits.

Validation errors

Returned when the request payload is missing required fields or has the wrong shape.

Status Message Endpoint
400 No movie JSON received POST /v2/movies
400 Error parsing movie JSON or the movie was empty POST /v2/movies
400 No valid movie JSON received POST /v2/movies
400 Project ID must be a 16-character string. Received ID: '…' (length: N) GET /v2/movies
400 Invalid start date / Invalid end date GET /v2/movies
400 Maximum date range is 3 months. GET /v2/movies
400 No payload provided POST /v2/templates, POST /v2/media/file, PUT /v2/media/file, DELETE /v2/media/file
400 Tags must be a string or an array POST /v2/templates
400 Payload movie must be a JSON string or JSON object POST /v2/templates
400 Template movie is not valid JSON or it's too large POST /v2/templates
400 name is required /v2/media/file
400 contentType is required POST /v2/media/file
400 size is required and must be a positive number POST /v2/media/file
400 path is required / Invalid path: no filename GET /v2/media/file
400 destination is required PUT /v2/media/file
400 folder is required / Invalid folder name /v2/media/folder
400 Cannot delete root folder / Cannot delete the temp folder DELETE /v2/media/folder
400 Folder is not empty. Delete all files first. DELETE /v2/media/folder
400 Invalid movie status Render submission
404 Template {id} not found /v2/templates, POST /v2/movies (template ref)
404 File not found /v2/media/file
404 Movie ID {id} not found Render submission
403 Template {id} is not owned by you / Movie ID {id} is not owned by you POST /v2/templates, render submission
405 Method not supported All endpoints
409 A file with this name already exists. Delete it first. POST /v2/media/file
409 A file with this name already exists in the destination folder PUT /v2/media/file
413 File exceeds maximum size of 500 MB POST /v2/media/file

Rendering errors

Surfaced asynchronously via GET /v2/movies when movie.status = "error". The movie.message field contains the underlying error. Examples seen in production:

Family Example message Trigger
Element validation Scene #1 Element #2: The element type 'video' requires a 'src' property. A required field was missing or null.
Positioning / sizing /Movie/scenes[0]/elements[1]: 'x' has an invalid value "auto". Use a number in pixels, a percentage of the canvas like "30%", one of: left, center, right x, y, width or height held a value that is neither a number nor one of the accepted strings. See Positioning and sizing values.
Asset download Asset fetch errors propagate from the downloader. The element src URL is unreachable, requires authentication, or returns an unsupported media type.
Webpage capture Errors from the HTML / webpage renderer. An html element pointed at a URL that timed out, returned non-2xx, or required interaction.
Voice synthesis Errors from the speech provider. Invalid voice ID, unsupported language, rate-limit, or a transient 5xx. For voices on your own ElevenLabs key, see below.
Subtitles Speech-to-text transcription error. Source audio was missing or unreadable.

For rendering errors, the movie.success field is false even though the HTTP status is 200.

Voices on your own API key

When an ElevenLabs voice runs on your own key — your default key (★) or a key chosen with connection — a failure never falls back to JSON2Video's key. The render fails with one of these messages (prefixed with Scene #n, element #m: ):

Message Cause Fix
Voice "<voice>" was not found in your ElevenLabs account. Use a voice ID from your ElevenLabs account, or a voice listed at https://json2video.com/ai-voices/elevenlabs/. The key works, but the voice is not in the ElevenLabs account the key belongs to. Add the voice to that ElevenLabs account, or use another voice.
Voice "<voice>" cannot be used with your ElevenLabs account: <reason>. … The ElevenLabs account has no access to that voice. Use another voice, or check the voice in ElevenLabs.
Your default ElevenLabs key (connection "<id>") failed: <reason>. Update it in Dashboard → Connections, or remove its star (★) there. To use JSON2Video's key in one render, set "connection": "none". Your default key was rejected, is out of quota or credits, has a payment problem or lacks a permission — or the connection was deleted while the render ran. Replace the key in Dashboard → Connections, remove its star, or set "connection": "none" on the voice.
The ElevenLabs key in connection "<id>" failed: <reason>. Update it in Dashboard → Connections. The same, for a key chosen with connection. Replace the key, or reference another connection.
Connection <id> not found in your list of connections. Add your connection from the dashboard. No connection has the ID in connection. IDs are case-sensitive. Fix the ID or create the connection.
Could not read your connections to check for a default API key. Please try the render again. A temporary error while looking up your default key. Render again.

Any other ElevenLabs error is shown with the reason ElevenLabs gives. See the voice element's connection property.

On JSON2Video's key, voices are limited to the ElevenLabs catalog: an unknown voice fails with Voice "<voice>" is not found in the list of supported voices for ElevenLabs. …, and a catalog voice with a higher credit cost with Voice "<voice>" has a credit cost of <n>x. Only 1x voices are supported with JSON2Video API keys. Use your own ElevenLabs API key to generate this voice.

Delivery errors

Output destinations (webhooks, FTP, SFTP, email) run after the render. A failed delivery does not change the movie's status: it is recorded in movie.destinations_result (Get movie status) and in the dashboard under Render logs → the render → Deliveries. Examples of message:

Status Example message Meaning
ok Delivered to https://example.com (HTTP 200, 3 attempts). Delivered, here after two retries.
error The receiver at https://example.com answered HTTP 404. Not retried. Your receiver answered with a 3xx or 4xx status.
error The receiver at https://example.com answered HTTP 503 (3 attempts). Your receiver kept answering with a 5xx status.
error No response from https://example.com within 30 s (1 attempt). The receiver may still have processed the request, so it was not sent again. Your receiver took more than 30 seconds to answer.
error Could not reach https://example.com: … (3 attempts). DNS, connection or TLS error.
error Not delivered: https://example.com resolves to a private, loopback or link-local network address. JSON2Video only connects to public internet addresses. The host points at a non-public address. Nothing was sent.
error Connection "<id>" was not found. Create it in Dashboard → Connections, or remove it from the movie. The destination id does not exist.
error The password of connection "<id>" could not be read. Save the connection again in Dashboard → Connections. Enter the password again in the dashboard.
error A movie can deliver through one export only, and this one has 2. Nothing was delivered. Put every destination in a single exports object.
error … Stopped retrying: the delivery ran out of time. / Not attempted: the delivery ran out of time. All destinations share a budget of about 5 minutes.
skipped Nothing to upload: the render did not produce a video. FTP, SFTP and email destinations of a failed render.
skipped aws-s3 destinations are not supported yet. Nothing was delivered. Amazon S3 is not available as a destination.

Connections (dashboard)

Messages shown in Dashboard → Connections when saving or testing:

Message Cause
You can run up to 20 tests per hour. Try again after HH:MM UTC. More than 20 tests (keys and destinations together) in the current hour. Tests refused before contacting anything do not count.
ElevenLabs API keys start with "sk_". Check that you copied the whole key. The key does not look like an ElevenLabs key.
A connection with this ID already exists. Choose another ID. IDs are unique per account.
"none" is reserved: "connection": "none" tells a render to use JSON2Video's own key. Choose another ID. none cannot be used as an ID.
The ID looks like an API key. IDs are not encrypted: … Don't put secrets in IDs.
The ID can only contain lowercase letters, numbers, "-" and "_", and must start with a letter or a number. See Connection IDs.
The webhook URL must start with https:// Webhooks are saved with https:// URLs only.
The webhook URL cannot point at localhost: JSON2Video calls it from the internet. Also for private IP addresses and JSON2Video's own API.
Enter only the host name, without ftp:// or sftp:// FTP/SFTP host must be a bare host name or IP.
The port must be a whole number between 1 and 65535 (21 for FTP, 22 for SFTP). Invalid port.

Timeouts

When a render is running for more than 15 minutes, GET /v2/movies returns movie.status = "timeout" with message = "Movie took too long to render". The original render may still eventually complete; treat timeout the same as error for client code paths.

Retry guidance

Class Retry strategy
400 validation Do not retry. Fix the payload.
401 quota Do not retry until credits are topped up.
403 auth Do not retry. Fix the key or role.
404 not found Do not retry. Confirm the ID.
409 conflict Do not retry blindly. Resolve the conflict (rename, delete the existing file).
500 internal Retry with exponential backoff, up to 3–5 attempts.
movie.status = "error" Inspect the message. Re-submit a fixed payload if the cause was client-side.
movie.status = "timeout" Re-submit the same job; treat as a transient failure.
← Previous: WebhooksNext: File retention →