Errors

When a request fails, the status is 4xx or 5xx and the body is JSON with two fields:

{"Code":422,"Message":"the input file is password-protected"}

Code repeats the HTTP status. Message is written for a person: it names the parameter, the limit or the reason. Branch your code on the status code, and log the message. Message texts can change between releases, so don't match on them.

Status codes

Three different limits answer 429, and the message says which one you reached: your account's rate limit, your plan's conversions at once, or your plan's conversions for the month. Each one sets Retry-After, and the waits are very different, so read it before you retry (Retry-After).

A 503 usually means our servers are busy for a moment. It can also mean that conversions on your plan are paused for a while; the message says so.

A 403 means the key's plan isn't set up on our side. Write to support@pdfconversionapi.com if you get one.

A 422 also covers a file we could read but won't convert as asked: a PDF whose owner restricted what readers may do, sent without its owner password, or a digitally signed PDF that the conversion would rewrite. The messages below say which.

A 500 means the failure is on our side: either our gateway or a conversion container hit an unexpected error (internal error), or an engine failed on the file in a way we didn't anticipate (the conversion failed: ..., followed by the reason).

Messages you'll see

These are the messages behind the most common errors. Names, numbers and formats in them come from your request; a part in italics is a reason that varies.

Responses that aren't JSON

A few error responses don't have our JSON body, so don't assume every body parses. When one doesn't, fall back to the status code and the Content-Type:

• A 413 from the edge network. Our cloud provider's network sits in front of our API and has its own limit on request size. A request close to 100 MB can be refused there before it reaches us. That 413 is an HTML page from the provider, and it has no x-request-id header. Handle it like any other 413: send less data in one request.
• A 400 for a body that isn't a multipart form. A JSON body, a urlencoded body, or a form without a boundary gets a 400 with the plain-text body Invalid `boundary` for `multipart/form-data` request. See Requests.
• A 504 with an empty body. A container that hasn't answered after 170 seconds (Limits) gives up without writing a body. The Content-Type still says application/json, so a JSON parser fails on it.
• The edge network's own error pages. If our gateway fails before it can answer, our cloud provider sends an HTML error page with a 5xx status. Like the edge 413, it has no x-request-id.

The retry examples below read error bodies this way.

Which errors to retry

Sending the same conversion again is safe: a conversion changes nothing on our side, except that with StoreFile=true each successful request stores its own copy of the result, which expires after 3 hours. Each attempt counts toward your rate limit. Only a successful attempt counts toward your plan's conversions a month.

Before you see a busy 503 (the server is busy; retry shortly), the API has already retried for you: for requests up to 25 MB, our gateway sends a busy request up to two more times, each time to a container picked at random. Larger requests stream straight through to one container and are not retried on our side.

A timeout in your own client doesn't stop the conversion on our side, so retrying right away runs a second conversion of the same file. Give your client enough time instead: the examples below use 240 seconds, and Limits explains where that number comes from.

Retry-After

429 and 503 responses carry a Retry-After header with a whole number of seconds:

Treat it as the shortest wait, not an exact one. If every client that got a 503 retries exactly 5 seconds later, they all arrive at the same moment and meet a busy server again.

A long Retry-After means that a retry loop won't help soon. The Python and Node.js examples below retry only when it is 60 seconds or less, and otherwise stop with the message. When the month's conversions are used up, stop sending conversions until the date in the message. GET /v2/usage shows how many are left before you get there.

Backoff with jitter

The Python and Node.js examples below retry failed connections, and 429 and 503 responses whose Retry-After is 60 seconds or less, up to 5 attempts in all. Before each retry they wait the Retry-After seconds plus a random extra delay whose upper bound doubles each time: up to 2 seconds after the first attempt, then 4, 8 and 16. A failed connection has no Retry-After, so only the random delay applies. The random part, called jitter, spreads clients out so they don't retry in step. Every other error is raised with its message and its x-request-id.

Each example converts report.docx to PDF. Download our test document (26 KB) and save it under that name to try them.

curl -sS --retry 4 --retry-max-time 120 -X POST https://api.pdfconversionapi.com/v2/convert/docx/to/pdf \
  -H "Authorization: Bearer $PDFCONVERSIONAPI_KEY" \
  -F File=@report.docx \
  -o response.json

# Needs the requests package: pip install requests
# Save it as convert_with_retries.py and run: python convert_with_retries.py
import base64
import os
import random
import time

import requests

API = "https://api.pdfconversionapi.com"
RETRY_STATUSES = {429, 503}
MAX_ATTEMPTS = 5
MAX_WAIT = 60  # seconds; a longer Retry-After (a used-up month, paused conversions) is raised


def convert(path, from_format, to_format, params=None):
    """Send one file. Retries short 429 and 503 waits and failed connections; raises on other errors."""
    with open(path, "rb") as f:
        content = f.read()
    url = f"{API}/v2/convert/{from_format}/to/{to_format}"
    headers = {"Authorization": f"Bearer {os.environ['PDFCONVERSIONAPI_KEY']}"}

    for attempt in range(1, MAX_ATTEMPTS + 1):
        try:
            response = requests.post(
                url,
                headers=headers,
                files={"File": (os.path.basename(path), content)},
                data=params or {},
                timeout=(10, 240),
            )
        except requests.ConnectionError:
            if attempt == MAX_ATTEMPTS:
                raise
            time.sleep(random.uniform(0, 2**attempt))
            continue

        if response.status_code in RETRY_STATUSES and attempt < MAX_ATTEMPTS:
            retry_after = float(response.headers.get("Retry-After", 1))
            if retry_after <= MAX_WAIT:
                time.sleep(retry_after + random.uniform(0, 2**attempt))
                continue

        try:
            body = response.json()
        except ValueError:
            body = None  # Not JSON, for example the edge network's own 413 page.
        if response.status_code == 200 and body is not None:
            return body
        if body is not None:
            message = body.get("Message")
        else:
            message = f"non-JSON response ({response.headers.get('Content-Type')})"
        request_id = response.headers.get("x-request-id", "none")
        raise RuntimeError(f"HTTP {response.status_code}: {message} (x-request-id: {request_id})")


if __name__ == "__main__":
    result = convert("report.docx", "docx", "pdf")
    for file in result["Files"]:
        with open(file["FileName"], "wb") as out:
            out.write(base64.b64decode(file["FileData"]))
        print(file["FileName"], file["FileSize"], "bytes")

// Needs Node.js 20 or later.
// Save it as convert-with-retries.mjs and run: node convert-with-retries.mjs
import { readFile, writeFile } from "node:fs/promises";
import { basename } from "node:path";

const API = "https://api.pdfconversionapi.com";
const RETRY_STATUSES = new Set([429, 503]);
const MAX_ATTEMPTS = 5;
const MAX_WAIT = 60; // seconds; a longer Retry-After (a used-up month, paused conversions) is thrown
const sleep = (seconds) => new Promise((resolve) => setTimeout(resolve, seconds * 1000));

/** Send one file. Retries short 429 and 503 waits and failed connections; throws on other errors. */
async function convert(path, from, to, params = {}) {
  const content = await readFile(path);
  for (let attempt = 1; ; attempt++) {
    const form = new FormData();
    form.append("File", new Blob([content]), basename(path));
    for (const [name, value] of Object.entries(params)) form.append(name, value);

    let response;
    try {
      response = await fetch(`${API}/v2/convert/${from}/to/${to}`, {
        method: "POST",
        headers: { Authorization: `Bearer ${process.env.PDFCONVERSIONAPI_KEY}` },
        body: form,
        signal: AbortSignal.timeout(240_000),
      });
    } catch (error) {
      // A failed connection rejects with a TypeError. Our own timeout (TimeoutError) is not retried.
      if (error.name !== "TypeError" || attempt === MAX_ATTEMPTS) throw error;
      await sleep(Math.random() * 2 ** attempt);
      continue;
    }

    if (RETRY_STATUSES.has(response.status) && attempt < MAX_ATTEMPTS) {
      const retryAfter = Number(response.headers.get("retry-after") ?? 1);
      if (retryAfter <= MAX_WAIT) {
        await response.body?.cancel();
        await sleep(retryAfter + Math.random() * 2 ** attempt);
        continue;
      }
    }

    const text = await response.text();
    let body = null;
    try {
      body = JSON.parse(text);
    } catch {
      // Not JSON, for example the edge network's own 413 page.
    }
    if (response.status === 200 && body) return body;
    const message = body?.Message ?? `non-JSON response (${response.headers.get("content-type")})`;
    const requestId = response.headers.get("x-request-id") ?? "none";
    throw new Error(`HTTP ${response.status}: ${message} (x-request-id: ${requestId})`);
  }
}

const result = await convert("report.docx", "docx", "pdf");
for (const file of result.Files) {
  await writeFile(file.FileName, Buffer.from(file.FileData, "base64"));
  console.log(file.FileName, file.FileSize, "bytes");
}

How each version handles retries and time limits:

• curl: --retry honors Retry-After (curl 7.66 or later) and otherwise doubles its wait, starting at 1 second. It adds no jitter, and it also retries 408, 500, 502 and 504 responses. --retry-max-time stops it from starting new attempts after that many seconds. When Retry-After is longer than --retry-max-time, as on a used-up month or paused conversions, curl doesn't retry and saves the error response.
• Python: timeout=(10, 240) gives up if the connection takes more than 10 seconds to open, or if no data arrives for 240 seconds. A read timeout raises requests.ReadTimeout, which the function doesn't retry.
• Node.js: AbortSignal.timeout(240_000) stops a request after 240 seconds in all, upload and download included.

We ran the three examples on 2026-11-01 against the API server running locally in a container, with only the base URL changed, through a small test proxy that answered the first request with our 503 response (Retry-After: 5) and the second with our 429 response (Retry-After: 10), then passed requests through. Each one waited at least 5 and then 10 seconds, and its third attempt returned the PDF. Versions: curl 8.7.1, Python 3.14.2 with requests 2.34.2, Node.js 24.15.0.

On 2026-11-02 we added the 60-second limit on waits to the Python and Node.js examples and ran them again against a small test server that stood in for the API. Given the same 503 and 429 and then a successful response, both waited as before and saved the file. Given the 429 for a used-up month, or the 503 for paused conversions (Retry-After: 600), both stopped after the first request and raised the message. The curl command above, with curl 8.7.1, also stopped after the first request in both cases and saved the error in response.json.

The request id: x-request-id

Every response from our API has an x-request-id header, errors and stored-file downloads included. On the hosted API it is a random UUID, new for each request. A response without it came from our cloud provider's network in front of the API, not from us.

Log the id next to your own record of each call. When you write to support@pdfconversionapi.com about a failed request, send:

• the x-request-id,
• the time of the request, with its time zone,
• the endpoint, for example /v2/convert/docx/to/pdf, and the parameters you sent,
• the status code and the Message.

Don't send your API key. If the file itself may be the cause, tell us whether you can share it; we don't keep a copy of anything you convert unless you stored it with StoreFile=true.

To read the id with curl, add it to the -w output (curl 7.84 or later):

curl -sS -o response.json -w '%{http_code} %header{x-request-id}\n' -X POST \
  https://api.pdfconversionapi.com/v2/convert/docx/to/pdf \
  -H "Authorization: Bearer $PDFCONVERSIONAPI_KEY" \
  -F File=@report.docx

In Python it is response.headers.get("x-request-id"), and in Node.js response.headers.get("x-request-id").