Reference · Errors and status codes

Errors and status codes

Every error has one shape, whatever the endpoint: ok is false and error says what went wrong in a sentence. No error is ever charged.

The shape

HTTP/1.1 404 Not Found
X-Request-Id: job_0mv6io8lccjzfdcme0rft6oj

{
  "ok": false,
  "error": "Directory not found"
}

Every response, error or not, carries an X-Request-Id header. Quote it when you write to us about a request.

Status codes in use
200	The request succeeded. For a processing or probe request, it was charged.
202	An async job was queued. Nothing is charged until it completes.
400	The request is wrong as sent: malformed JSON, a missing or invalid field, a refused option or filter, a URL that isn’t public HTTPS.
401	The `Authorization` header is missing, or the key is invalid, revoked or expired.
403	The account isn’t active, or a file is over 5 GB. The error says what to do.
404	The directory, file or job isn’t in your account, or has expired. Also any path or method the API doesn’t have.
409	The request conflicts with what is there: a file name that is already uploaded, a job that can no longer be cancelled.
410	`POST /ffmpeg/run` only. It is retired; use `POST /ffmpeg/process`.
429	Over 300 requests a minute on one key, or 50 jobs in progress at once. The response carries `Retry-After`.
500	FFmpeg or ffprobe failed, a job ran out of time, or something broke on our side. The error says which.
501	The `/ai/…` endpoints only. They are not offered.
503	Too busy to start a synchronous job now. The response carries `Retry-After`; the async endpoint queues instead.

Error messages by status code
401	`Authorization Header Required`
401	`Invalid API key`
403	`Add a card at media.logicboostkit.com/console to start using the API.`
403	`A payment failed. Pay the open invoice at media.logicboostkit.com/console to resume.`
403	`This account is suspended. Contact contact [at] logicboostkit [dot] com.`
403	`File 'source.mov' size (5120.00 MB) exceeds max file size limit of 5 GB.`
400	`Request body is required`
400	`Invalid JSON in request body`
400	`Task object is required in request body`
400	`Invalid file_path format. Expected <dir_id>/<file_name>`
400	`All input files must be from the same directory`
400	`Output filename 'source.mp4' conflicts with an existing input file`
400	`Invalid task format: inputs must be a non-empty array`
404	`Directory not found`
404	`File not found in directory`
404	`Job not found`
409	`File name already exists in directory`
409	`Cannot cancel job in 'processing' status. Only pending jobs can be cancelled.`
429	`Rate limit exceeded: 300 requests a minute per key. Retry shortly.`
500	`FFmpeg command failed with exit code 1: …`
500	`Processing timed out`
503	`Too busy to start the job now. Retry, or use the async endpoint, which queues it.`

Match on the status code, not on the text. The text is written for a person and may be made clearer.

429 and 503: wait for the number of seconds in Retry-After, then send the same request again.
500: read the error first. If FFmpeg failed, the same task will fail again; fix its options. If the fault was ours, retry.
400, 401, 403, 404 and 409: the request has to change before it can succeed.