Errors
Every status code and error message the API returns.
Errors are JSON with a single error field and an HTTP status.
{ "error": "Missing or invalid API key." }A job that was accepted and then failed is not an HTTP error. Its response is status 202 or 200 with "status": "failed" and an error field. Those messages are listed under Why a job fails.
In these tables, <n> and similar stand for values filled in by the API.
400 Bad request
Request bodies:
| Error |
|---|
Body must be JSON. |
webhook_url must be a URL. |
Expected an http(s) URL or a file id. |
Can't fetch <host>. |
POST /v1/run:
| Error |
|---|
ffmpeg_command is required. |
ffmpeg_command is limited to 10000 characters. |
Unterminated quote in ffmpeg_command. |
input_files and output_files must be objects. |
At most 10 input files and 10 output files. |
Declare at least one output in output_files. |
Bad input key "<key>". |
Bad output key "<key>". |
Input "<key>" must be a URL or file id. |
"<key>" is used for both an input and an output. |
Output "<key>" needs a plain file name with an extension, like out.mp4. |
Output name "<name>" is used twice. |
Unknown placeholder {{<key>}}. |
{{<key>}} is declared but never used in ffmpeg_command. |
The option <option> is not allowed. |
URLs and protocols can't be used inside ffmpeg_command. Declare them in input_files. |
Paths outside the job aren't allowed: <argument> |
Every -i must be an {{input}} placeholder, or follow -f lavfi. |
POST /v1/tools/<name>:
| Error |
|---|
input is required: a URL or file id. |
Unknown tool. Available: probe, compress, convert, resize, trim, thumbnail, extract-audio, gif. |
<field> must be a whole number from <min> to <max>. |
<field> must be seconds or a timestamp like 00:01:30. |
format must be one of mp4, webm, mov, mkv, mp3, m4a, wav, ogg, flac. |
format must be one of mp3, m4a, wav, ogg, flac. |
Give width, height, or both. |
Give end or duration. |
trim works on video and audio files with a common extension. |
Other statuses
| Status | Error | When |
|---|---|---|
| 401 | Missing or invalid API key. | The key is missing, wrong or revoked. |
| 402 | Your subscription isn't active. | Your paid plan isn't in good standing. |
| 403 | This account is suspended and can't run jobs. | The account is suspended. |
| 403 | Webhooks are on paid plans. See https://mediatofu.com/#pricing. | webhook_url on Free. |
| 404 | Job not found. | The job doesn't exist or isn't yours. |
| 404 | Not found. | Unknown path or method. |
| 411 | Send the file as the raw body, with a Content-Length. | Upload without a body or Content-Length. |
| 413 | Uploads are limited to <n> MB on your plan. | Upload too large. |
| 429 | Your plan runs <n> job(s) at a time. Wait for one to finish. | Concurrency limit. The API says job or jobs to match the number. |
| 429 | You've used your <n> free compute minutes this month. Upgrade at https://mediatofu.com/#pricing. | Free compute used up. |
| 429 | You've reached your $<n> spending cap for this period. | Spending cap reached. |
| 500 | Something went wrong on our side. | Unexpected server error. |
Download links return plain text instead of JSON: status 404 with Not found or expired., see Outputs and retention.