​

Errors

{
  "detail": "Missing url."
}

​

Codes

​

Common edge cases

• Empty file (0 bytes): responds 400 because there is no content to convert.
• Unrecognized format (unsupported extension and generic content-type): responds 415. Force input_format explicitly if you know the real format and the filename does not make it clear.
• Corrupt PDF or invavalid header: usually 400 during early vavalidation, or 500 if extraction fails. Try mode=quality before discarding the document.
• Invavalid or unreachable URL on /convert/from-url: 400 if the URL format is invavalid, 403 if the host is not allowed, 502/504 if the remote storage does not respond or drops the connection mid-download.
• Conversion timeout: for very large documents or many images, the API may take longer than your HTTP client expects by default. Set a generous timeout (300s or more) on clients like httpx/fetch; if the system is saturated you will receive 202 instead of blocking the connection. See Jobs.
• ZIP without any supported document inside, or with more files than MAX_ZIP_FILES: 413 or 415 depending on the case; the message indicates which limit was violated.

​

Retries

• 429 and 5xx: retry with exponential backoff (for example 1s, 2s, 4s, with jitter).
• 4xx (except 429): do not retry without correcting the request. The error will not disappear by repeating the same call.
• 202: not an error. It is the signal that you should start polling GET /jobs/{id}.

import httpx, time

def convert_with_retry(url, headers, json_body, max_retries=3):
    for attempt in range(max_retries):
        r = httpx.post(url, headers=headers, json=json_body, timeout=300)
        if r.status_code == 200:
            return r.text
        if r.status_code == 202:
            return None  # manejar con polling a /jobs/{id}
        if r.status_code in (429, 500, 502, 503, 504):
            time.sleep(2 ** attempt)
            continue
        r.raise_for_status()  # 4xx no reintentable
    raise RuntimeError("Maximum retries reached")

async function convertWithRetry(url, headers, body, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const res = await fetch(url, { method: "POST", headers, body });
    if (res.status === 200) return res.text();
    if (res.status === 202) return null; // handle by polling /jobs/{id}
    if ([429, 500, 502, 503, 504].includes(res.status)) {
      await new Promise((r) => setTimeout(r, 2 ** attempt * 1000));
      continue;
    }
    throw new Error(`Non-retryable error: ${res.status}`);
  }
  throw new Error("Maximum retries reached");
}