Errors

Errors return JSON with an error string.

{
  "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. Enable overage in Settings → Usage on Pro+ when your plan supports it, or upgrade via Pricing.

Error handling pattern

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

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}`);
}

Getting Started

Image CDN

Media Platform

SDKs & Integrations

Resources

Status codes

Retry guidance

Error handling pattern

​Status codes

​Retry guidance

​Error handling pattern

Status codes

Retry guidance

Error handling pattern