> ## Documentation Index
> Fetch the complete documentation index at: https://docs.convertly.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Common Convertly API error responses.

Errors return JSON with an `error` string.

```json theme={"system"}
{
  "error": "Missing API key."
}
```

## Status codes

| Status | Meaning                                                                                 |
| ------ | --------------------------------------------------------------------------------------- |
| `400`  | Invalid settings, invalid JSON, or missing required form fields.                        |
| `401`  | Missing, invalid, or unauthenticated API key/session.                                   |
| `402`  | Monthly quota exceeded and overage is not enabled.                                      |
| `403`  | Plan limit, locked format, storage limit, or feature restriction.                       |
| `404`  | Job, file, folder, or webhook was not found.                                            |
| `409`  | The requested action conflicts with current state, such as cancelling a processing job. |
| `413`  | Uploaded file exceeds the current plan file-size limit.                                 |
| `415`  | Unsupported media type or unsupported compression format.                               |
| `429`  | Per-minute rate limit or anonymous limit exceeded.                                      |
| `500`  | Convertly could not complete the request.                                               |
| `503`  | Queue or storage dependency is unavailable.                                             |

## Retry guidance

Retry `429` after the current minute window resets. Retry `503` with backoff. Do not retry `400`, `401`, `403`, or `415` without changing the request.

`402` and monthly-cap `429` responses mean the workspace hit a plan quota with overage disabled or unavailable on that tier. Check response quota headers when present, then compare against [Limits](/limits). Enable overage in **Settings → Usage** on Pro+ when your plan supports it, or upgrade via [Pricing](https://convertly.sh/pricing).

## Error handling pattern

Read the API key from a server environment variable. Never hardcode keys in source files or commit them to git.

```ts theme={"system"}
const apiKey = process.env.CONVERTLY_API_KEY;
if (!apiKey) {
  throw new Error("Missing CONVERTLY_API_KEY");
}

const formData = new FormData();
formData.set("file", file);

const response = await fetch("https://convertly.sh/api/media/inspect", {
  method: "POST",
  headers: {
    authorization: `Bearer ${apiKey}`,
  },
  body: formData,
});

if (!response.ok) {
  const body = await response.json().catch(() => ({}));
  throw new Error(body.error ?? `Convertly request failed with ${response.status}`);
}
```