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 anupload_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 answers200 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.
gallery_not_found
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.
Instant links
An instant link answers with a picture, so its refusals aren’t JSON. Each is plain text with the code in anx-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.
link_expired
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.
link_orphaned
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.
link_limit
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 answers200 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.

