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
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

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.

## Messages you may meet

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.

## What to retry

- **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.