Skip to main content
Every error has the same shape:
Every response carries X-Request-Id, success or error. Send your own X-Request-Id (8–128 letters, digits, ., _, : or -) and we use it instead of minting one. Over MCP, a JSON-RPC error carries the same code, doc_url, request_id and param in its data. A tool that ran and refused comes back as a tool result with isError: true. A 202 isn’t an error. The job or run was accepted and is still running. Poll poll_url.

Keys and access

missing_key

401. No Authorization header, or it isn’t Bearer …. Send Authorization: Bearer mm_live_…, or a mm_test_… key to try things for free. See Authentication.

invalid_key

401. The key is unknown, revoked, or mistyped. Check you copied the whole key. Mint another at mediamonster.app/keys if it was revoked.

key_expired

401. The key was minted with an expiry date, and that date has passed. The message says when. Mint a new key at mediamonster.app/keys, move the integration over, and revoke the old one. See Expiry.

insufficient_scope

403. The key wasn’t minted with the scope this call needs. The message names it. Over MCP, the same for a tool an app you signed in to wasn’t allowed. Scopes are fixed at mint. Mint a key with the scope, or sign the app in again and allow it.

ip_not_allowed

403. The key has an address allow-list, and this call came from outside it. The message says which address it came from. Call from an address on the list, or mint a key whose list includes this one. See Address allow-list.

plan_required

403. A paid-only skill on Cyclops, a step in the steps that is paid-only, or an automation feature the plan doesn’t include. Move up a plan, or pick a skill that isn’t paid-only. GET /api/v1/skills marks them paid_only.

over_seats

403. The key’s workspace has more people than its plan seats. Until that is fixed, only its owner can spend its credits. The workspace owner removes people or moves up a plan.

sign_in_required

401. A skill or a recipe that spends credits was reached without an account. Send a key. Only free tools run without one.

not_allowed

403. Your role in the workspace doesn’t allow this: adding files to a Vault folder you can only view, changing an automation you didn’t make, or a guest reaching outside their folders. Ask the workspace owner for edit access, or pick a folder you can add to.

guest

403. A guest in a workspace tried something only members can do. Ask the workspace owner to make you a member.

test_mode_unsupported

403. A test key (mm_test_…) tried to change the Vault, an automation or a gallery. A test key changes nothing real, and those have no stand-in to hand back. Use a live key for this. A test key can still read them. See Test mode.

Limits

rate_limited

429. Too many requests this minute — on this key, or across every key on the account. The message says which. retry-after says how many seconds to wait, and the X-RateLimit-* headers say where you stand. Wait retry-after seconds and try again. A key over its own limit is one script to slow down; an account over its total can’t be fixed by moving work to another key. See Rate limits.

rate_limit_unavailable

503. The limiter couldn’t count the request, so it couldn’t let it through. Wait retry-after (5 seconds) and try again.

plan_limit

403. The plan’s fence: a source longer than it takes, more AI steps than it runs at once, more files than its batch, or more Vault room than it holds. The message names the plan that lifts it. Split the work, shorten the source, or move up a plan. See Limits.

free_tool_limit

429. Cyclops’s daily cap on free-tool runs. Wait for tomorrow, or move up a plan.

insufficient_credits

402. The run costs more than the balance. Auto top-up, if it is on, has already tried. Top up, or wait for the monthly reset. A dry_run=true call tells you this before you try: see Dry runs.

Idempotency

bad_idempotency_key

400. The Idempotency-Key header isn’t 1–255 printable characters. Send a UUID, or any printable string up to 255 characters. See Idempotency.

idempotency_key_reused

422. That key was already used for a different request — another path, or a different body. Use a new key for a new request. Reuse a key only to retry exactly the same request.

idempotency_in_progress

409. A request with that key is still running. Wait retry-after (2 seconds) and send it again. Once the first finishes, the retry gets its answer.

idempotency_unavailable

503. The key couldn’t be checked, so the request wasn’t run — running it might have run it twice. Wait retry-after (5 seconds) and send it again with the same key.

Sending a file

missing_file

400. The skill or the steps need a file, and none was sent. Send file, url, job_id or asset_id.

unexpected_file

400. The first step makes its own file from a prompt, and a file was sent with it. Leave the file off, or start the steps with a step that takes one.

bad_file

400. Under the 64-byte floor (12 for text), or the bytes aren’t the type they claim to be. Send the file itself, not a page about it. Check the upload finished.

file_too_large

413. Over the plan’s ceiling for that kind of media, or a request body over 100 MB. Send anything over 100 MB as a public url, or upload it through the app and pass its job_id. See Formats.

unsupported_media

415 for a file we don’t take at all; 400 when Convert was sent audio or a document, or a step can’t file a result in the Vault. Check the skill’s accepts on GET /api/v1/skills. Audio and documents have their own skills.

wrong_input

400. The skill doesn’t take that kind of file — captions on a picture, say. Check accepts on GET /api/v1/skills, or add a step that makes the kind it takes.

bad_url

400. Not http or https, a private address, or a Mediamonster link. param is url. Send a public http(s) URL. For a file that is already here, send its job_id.

fetch_failed

400. The URL didn’t answer, answered with an error, redirected too often, or took too long. Open the URL yourself. It has to be public and reachable without signing in.

bad_job_id

400. job_id isn’t a job id. param is job_id. Send the id from an earlier job’s response.

job_not_found

404. No job with that id on this account. Check the id. Jobs are swept after a while; re-upload if it has gone.

no_source

400. The job_id names a job made from a prompt, so it has no source file to run again. Send the file it made, by url or as a Vault file’s asset_id.

upload_unfinished

409. The job’s upload hasn’t finished, or hasn’t been checked yet. Wait for the upload to finish, then try again.

upload_completing

409. Another complete for the same upload is running. Ask again in a moment; it answers with the checked upload once the first has finished.

upload_not_landed

409. A new version’s bytes never arrived. Upload the file again, then add the version.

job_busy

409. That job is already running or queued. Wait for it, or poll its poll_url.

job_lost

500. The job vanished while we were running it. Try again. If it happens twice, quote the request_id to support.

invalid_job

400. job_id on POST /api/v1/assets or a new version isn’t a job id. Send the id of a finished upload or run.

job_not_finished

409. That job isn’t finished, so there is nothing to store yet. Wait for status: complete, then store it.

nothing_to_save

422. The job made words or facts but no file, so there is nothing to put in the Vault. Read its text or data from the job instead.

Direct uploads

The codes of direct uploads, and of a run given an upload_id.

missing_file_name

400. POST /api/v1/uploads with no file_name. Send the file’s name, with its extension: the extension is part of how its type is checked.

bad_size

400. size_bytes is missing, or isn’t a whole number of bytes above zero. Send the file’s exact size in bytes. The upload is checked against it when it lands.

missing_parts

400. A multipart upload was completed with no parts. Send parts: every part’s part_number and the etag R2 answered its PUT with.

bad_parts

400. A part is missing, sent twice, or has no etag. The message says which. Send every part from 1 to the number the upload was opened with, once each.

upload_incomplete

400. The parts didn’t fit together — a part that wasn’t PUT, or an etag that isn’t the one it was answered with. PUT any part that failed again, then complete the upload with the new etag.

bad_upload_id

400. upload_id isn’t an upload id. param is upload_id when a run was given it. Send the upload_id that POST /api/v1/uploads answered with.

upload_not_found

404. No upload with that id on this account. Check the id, and that the key belongs to the account that opened the upload.

upload_unavailable

503. Storage wouldn’t open the upload. Try again in a few seconds. Nothing was stored.

Skills and options

unknown_skill

404 on /run/{skill}; 400 as a step’s tool on /runs. No skill by that slug. GET /api/v1/skills lists them.

skill_offline

409. The skill isn’t switched on yet. Pick another skill. The caveat on GET /api/v1/skills says when.

unknown_option

400. The skill has no option by that id. param is the id you sent. Use the ids from GET /api/v1/skills. The message lists the valid ones.

retired_option

400. That option was removed. param is its id. The message says what replaced it.

bad_option

400. A value the option doesn’t take, a stretch past the end of the video, or variations past 4. param is the option at fault. The message lists the valid choices. For a range option, any whole number in range works.

missing_prompt

400. The skill needs a prompt. param is prompt. Send one. The message says what it is for.

prompt_too_long

400. The prompt is over 2,000 characters, or it’s an add-voiceover script that takes longer to read than the video runs. param is prompt. Shorten it. For a voiceover, the message says how many seconds to cut.

missing_reference

400. swap and try-on need a second image. param is reference_url. Send reference_url, reference_job_id or reference_asset_id.

bad_reference

400. The reference isn’t an image. Send a picture as the reference.

reference_not_found

404. No reference job with that id on this account. Check the id.

reference_not_ready

409. The reference image hasn’t finished uploading. Wait for it, then try again.

reference_not_image

400. The reference job isn’t an image. Send a picture.

bad_aspect

400. An aspect that isn’t in the list. param is aspect. The message lists them.

unsupported_format

400. Convert won’t write that format. param is format. Images: png, jpeg, webp. Video: mp4, webm.

nothing_to_join

400. A skill that joins several files was given one. Put it under a step that makes several, on POST /api/v1/runs.

render_unavailable

503 for a large video while the encoder is down; 422 for a step that needs the encoder and can’t have it. Try again in a little while.

unknown_tool

400. An MCP tool that doesn’t exist. Call tools/list for the names. On a tool set, the message says when the tool exists but isn’t in that set; /api/mcp offers every tool.

unknown_tool_set

404. An MCP server address after /api/mcp/ that names no tool set. Use runs, vault, or a comma list of groups. The message lists them.

invalid_argument

400. An MCP Vault tool was sent an argument it can’t use — an empty folder name, say. The message says which argument.

Steps and recipes

missing_steps

400. /runs with no steps and no recipe_id, or an empty list. Send steps or a recipe_id.

ambiguous_line

400. Both steps and recipe_id. Send one or the other.

bad_step

400. A step that isn’t an object, or has no tool. Every step is {"tool": "<slug>", "options": {…}}.

bad_line

400. A step in the wrong place: it can’t take what the step above it makes, it is indented under nothing, or a joiner has one file above it. The message names the step. Reorder the steps so each one is handed a kind of file it takes.

step_not_allowed

400. A step that can’t run in a recipe at all: send, or a skill that needs a second image. Run it on its own with POST /api/v1/run/{skill}.

step_unavailable

422. A step with no server version yet. Run it in the Workbench.

too_many_steps

400. More than 60 steps. Split the recipe in two.

too_many_files

400. Several files sent to steps that don’t open by joining them, or more than a join takes. Send one file per run, or start the steps with a join.

bad_recipe

400. recipe_id isn’t a recipe id, or the version asked for isn’t one: not a whole number from 1, on a ready-made recipe (they have no versions), @n and version saying different numbers, or version sent with inline steps. Send the id of a recipe saved in the Workbench, and a version as my-recipe@3 or "version": 3.

recipe_not_found

404. No recipe with that id on this account. Check the id.

recipe_version_not_found

404. The recipe is there, but never had the version asked for. The message says its latest. Leave the version off to run the latest, or ask for one it has. History on the recipe’s tile lists them.

bad_origin

400. GET /api/v1/recipes with an origin it doesn’t take. Send catalogue, mine or community, or leave it out for the ready-made recipes and yours.

bad_cursor

400. before on the community recipes isn’t a cursor we handed out. Send the next_before of the page above, as it came.

missing_input

400. The recipe’s steps use a {{name}} that has no default, and inputs didn’t send it. param is inputs.<name>. Send it in inputs, like {"title": "Summer sale"}. GET /api/v1/recipes/{ref} (or describe_recipe) lists every input under inputs, with which are required.

bad_input

400. A value that doesn’t fit its input: not a number, not an https:// link, not one of a choice’s values, or too long. param is inputs.<name>. The message says what it takes.

unknown_input

400. inputs sent a name the steps don’t use. Check the spelling against the recipe’s inputs. Names are matched without case, spaces or punctuation: Product Name is product_name.

bad_inputs

400. inputs isn’t an object. Send {"name": "value", …}. In a multipart form, send it as a JSON string, or one field per input named inputs[name].

bad_run_id

400. The run id in the path isn’t a run id. Send the id from POST /api/v1/runs.

run_not_found

404. No run with that id on this account. Check the id.

Batches

missing_rows

400. A batch with no rows, csv or matrix, or with nothing under the header. Send the rows one of those three ways.

ambiguous_rows

400. More than one of rows, csv and matrix. Send one of them.

bad_rows

400. rows isn’t a list of objects. Send [{"product": "shoe"}, {"product": "bag"}].

bad_matrix

400. A matrix list with no values, more than 4 lists, more than 50 values in one, two lists with the same name, or more combinations than a batch runs. The message says which. Trim the lists, or split the batch.

too_many_rows

400. More than 1,000 rows. Split the sheet into batches of 1,000 or fewer.

unknown_variable

400. A step or the naming pattern asks for a {{variable}} that no column is called. Rename the column or the variable. Headings are matched without case, spaces or punctuation: Product Name is {{product_name}}.

unknown_column

400. file_column names a column the rows don’t have. Send the column’s heading as it is in the sheet.

bad_check

400. check isn’t true or an object like {"retries": 1}. Send {"retries": 1}, up to 3.

bad_gate

400. A check on steps that don’t end on a picture. The check judges pictures. Turn the check off, or end the steps on an image.

bad_number

400. budget isn’t a number of credits. Send a whole number, or leave it out for no budget.

batch_not_found

404. No batch with that id, or it’s another account’s. Check the id. GET /api/v1/batches lists yours.

batch_over

409. resume on a batch that finished or was stopped. Run its rows again with rerun instead.

bad_review

400. review isn’t approved, rejected or null. Send one of those three.

bad_format

400. format on the results isn’t csv or jsonl. Ask for one of those two.

Codes on a failed step

A run that was accepted and then failed answers 200 with "status": "failed" and a sentence in error. These are the reasons a step can fail for. They reach you as that sentence, not as an HTTP error; the heading tells you what to do about each.

nothing_made

502. A step finished and made nothing the next step could work on. Its credits went back. Check the file suits the step — a clip with no speech has nothing to caption.

set_failed

502. A step failed on every file of a set. Read each file’s note in the run’s notes.

step_unfinished

504. A step ran out of attempts before it finished. Its credits went back. Run it again.

edit_failed

502. A resize or Save as couldn’t write the picture. Try again, or convert the file first.

unreadable_image

422. A picture step couldn’t read the file. Convert it to PNG or JPEG first.

nothing_to_resize

422. Resize was handed a sound file. Resize before the step that makes the sound file.

nothing_to_adjust

422. Adjust was handed a sound file. Adjust the video before extracting its sound.

not_a_picture

422. Compose puts pictures on a background, and was handed video or sound. Give it a picture.

target_too_small

422. The file is too small for the size asked. Ask for a smaller size.

faces_unplaced

502. Faces were found but couldn’t be placed to blur. Try again, or blur the file on its own.

nothing_to_clip

422. Clips found nothing worth cutting. Try a longer video, or pick the stretch with from and to.

Webhooks

bad_webhook

400. webhook_url isn’t an https URL on a public host. param is webhook_url. See Webhooks.

webhooks_off

503. Webhooks aren’t switched on for this deployment. Poll poll_url instead.

bad_request

400. A webhook endpoint’s url, events, description or overlap_hours isn’t one we take, the body isn’t a JSON object, or a delivery log status or cursor isn’t one we handed out. The message says which. Fix the field and send it again. See Webhooks.

endpoint_limit

409. The account already holds 10 webhook endpoints. Delete one you no longer use, or point one at a receiver that fans out.

endpoint_deleted

410. The delivery you asked to replay went to an endpoint that has since been deleted. Add the endpoint again, then replay the event to it.

The Vault, automations and galleries

bad_asset_id

400. asset_id isn’t a Vault file id. param is asset_id. Send an id from GET /api/v1/assets.

bad_sha256

400. POST /api/v1/assets/check was sent no sha256 list, more than 100 hashes, or one that isn’t 64 hex characters. param is sha256. The message names the entry. Send the file’s SHA-256 in hex.

file_not_found

404. No Vault file with that id that you can see. Check the id. A guest only sees the folders they were given.

file_gone

410. The Vault file’s bytes are gone. Upload it again.

invalid_asset

400. A gallery was sent something that isn’t a Vault file id. Send ids from GET /api/v1/assets.

too_many_assets

400. More files than one gallery takes in one call. Add the rest in a second call.

missing_title

400. A gallery with no title. Send a title.

invalid_body

400. The body isn’t the JSON object this endpoint takes. Send content-type: application/json and an object.

cdn_publishing_off

403. The Vault’s CDN link is switched off for this workspace. Switch it on in the Vault’s settings.

invalid_rule

400. An automation that can’t work as written — a recipe that can’t start from the kinds of file it wakes for, say. The message says what to change.

too_many_rules

409. The workspace holds as many automations as it can. Delete one first.

rule_not_found

404. No automation with that id you can see. Check the id.

not_ready

503. Automations aren’t set up on this deployment yet. Try again later.

delivery_not_found

404. No delivery with that id. Check the id. 404. No gallery with that id. Check the id.

folder_not_empty

409. The folder still holds files. Move or delete them first.

rights_expired

409. A file’s usage rights have run out, so it can’t be shared. Renew the rights on the file first.

field_not_found

404. No metadata field with that id. Check the id.

field_taken

409. A metadata field with that name already exists. Pick another name.

too_many_fields

409. The workspace holds as many metadata fields as it can. Delete one first.

invalid_field

400. A metadata field definition that doesn’t work. The message says which part.

invalid_metadata

400. A value that doesn’t fit its metadata field. The message says what the field takes.

invalid_release

400. A model or property release that isn’t complete. The message says what is missing.

invalid_rights

400. Usage rights that don’t make sense — an end before a start, say. Fix the dates.

no_match_column

400. A metadata import with no column to match files by. Add a file name or id column.

version_not_found

404. No version with that id on the file. List the versions with GET /api/v1/assets/{id}/versions.

version_is_current

409. That version is already the current one. Nothing to do.

version_order_invalid

409. A version order that doesn’t list each version once. Send every version id, once each.

version_failed

500. The new version couldn’t be written. Try again. Quote the request_id if it happens twice.

versions_unavailable

503. Versions aren’t set up on this deployment yet. Try again later.

wrong_kind

422. A version has to be the same kind of file as the one it replaces. Send a picture for a picture, a video for a video.

combine_invalid

422. Combining as versions needs at least two different files. Pick two or more.

combine_failed

500. The files couldn’t be combined. Try again. An instant link answers with a picture, so its refusals aren’t JSON. Each is plain text with the code in an x-mediamonster-error header, and none of them is cached.

bad_signature

403. The URL’s s doesn’t match its path and query under the link’s secret. Sign the final URL, after every parameter is set, with the link’s current secret. The SDKs’ instantLinkUrl and instant_link_url do it. A rotated secret stops every URL signed with the old one.

missing_signature

403. A signed link was asked for with no s. Sign the URL on your server. Only an open link answers without one. 410. The link’s expires_at has passed. Make a new link, or set a later date on this one in the app.

most_renders

403. The link has made as many new pictures as its most_renders allows. Pictures it made before still load. Raise the limit in the app, or make a new link.

bad_query

400. A size the template isn’t laid out for, a field value over 2,000 characters, or a parameter sent twice. The message says which. size takes the template’s own size, the ones it’s laid out for, or 1080x1080, 1080x1350, 1080x1920, 1920x1080 and 1200x630.

template_gone

404. The link’s template was deleted, or the version it’s pinned to no longer lays out. Make a new link on a template that’s there. 403. Whoever made the link has left its workspace, so there’s nobody to bill a new picture to. Make a new link from an account in the workspace. 409. The workspace already holds 100 instant links. Delete one you no longer use.

render_busy

503. Another request is still drawing the same picture, and it took longer than 45 seconds. Nothing was charged. Try again after Retry-After. The picture is drawn and billed once, however many ask for it at the same time.

render_failed

502. The picture couldn’t be drawn. Its credit went back. Try again in a minute.

Everything else

bad_json

400. The body, or a field holding JSON, doesn’t parse. Check the JSON. Over MCP, the whole request body has to be JSON-RPC.

method_not_allowed

405. That endpoint doesn’t take that verb. allow lists the ones it does. Use the method in allow.

not_found

404. Nothing at that link — an oEmbed request for a share link that is off or gone, a brand that doesn’t exist, or a webhook endpoint or delivery with that id on this account. Check the link or the id.

not_implemented

501. oEmbed only serves format=json. Ask for JSON.

api_unavailable

503. This deployment isn’t set up for keys yet. Try again later.

internal_error

500. Something we have to fix. The message never carries the cause; our log has it, under your request_id. Try again. If it keeps happening, send us the request_id.

When a job fails after it was accepted

A job that was accepted and then failed answers 200 with "status": "failed" and a sentence in error, written for a person: what happened, that any credits went back, and what to do. It never carries the provider’s own text, an exit code or an HTTP status. When the cause was on our side the sentence ends with the run id — …tell us the run id 6f2c… — which is the id to quote to support.