Skip to main content
Errors return JSON with an error string. 
{
  "error": "Missing API key."
}

​
Status codes

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