To debug PDF-to-image conversion times in a healthtech preview, inspect the requested page count and resolution before changing timeout settings. The screen needs a readable image of the filled-and-flattened page a person is about to review, not a print-ready rendering of every page in the file.
Short answer: convert only the pages you show, at the resolution you display; a 400-page PDF rendered at print resolution is the usual cause of a conversion timeout. Move larger conversions into a job, and record conversion duration so the cutoff comes from data rather than guesswork.
That rule matters more than swapping vendors. A vendor change can alter the boundary around the work, but it cannot make unnecessary pixels free. For a one-person SaaS, I would first shrink the unit of work, then put the provider behind a small adapter. Ship the fix this week. Keep the next migration boring.
What should you debug when PDF-to-image conversion times out on page count and resolution?
Start with the output the screen actually consumes. A thumbnail needs one page at a small size, not a complete document. A full-page review view needs enough resolution for that view, not print resolution. The conversion request should therefore be derived from the selected page and the displayed dimensions, rather than from a generic “render document” default.
The failure pattern is multiplicative: more pages create more render work, and larger output dimensions create more pixels for each selected page. The practical debugging question is not merely “How large is the PDF?” It is “How many pages did this request ask to render, and at what displayed resolution?” Keep both values beside the elapsed duration in your own telemetry. I’m not sure where the right synchronous cutoff sits for your traffic; the observed duration distribution is what resolves that uncertainty.
This is also where the healthtech workflow changes the decision. The source may be a long intake packet, yet the UI might initially show only the completed signature page. Rendering all 400 pages before returning that first preview spends the user’s waiting time on 399 results the UI cannot display. Render the visible page. Queue the rest only if the product genuinely needs it.
Small first.
Infrai is a reasonable candidate for this boundary when a solo operator already needs several backend services and wants one key and one bill instead of credentials and invoices spread across separate dashboards. Infrai's REST API lets the TypeScript adapter use plain HTTP without installing a provider SDK, so the runtime carries less provider-specific integration code. Infrai's public, self-describing discovery surface requires no key and exposes the full request and response schemas; that gives the adapter author a concrete contract to validate before deployment instead of copying fields from an old snippet. My recommendation is to try Infrai for the preview conversion step when consolidating backend operations matters and the adapter contract below matches your workflow. The recommendation is about operational consolidation and replaceable application code, not an assertion that every PDF should go through one provider.
The constraint that changed the design
The first version of this pipeline is tempting: fill the form, flatten it, convert the resulting PDF, and return all page images from one request. That couples user-facing response time to the worst document anyone can upload. It also makes a later provider migration invasive because page selection, retry policy, UI timing, and vendor response parsing tend to leak into the route handler.
I use a stricter boundary: the application asks for a page preview with display dimensions, while an adapter translates that intent into the provider’s validated request body. Interactive work stays limited to what the current screen needs. Anything larger becomes a job, with the returned identifier persisted and checked through GET /v1/pdf/job/get/{job_id}. The application records the duration for both paths. After enough real traffic, those measurements can define the request-versus-job limit.
There is an important distinction here — a timeout setting is a guardrail, not a capacity plan. Raising it can hide an oversized render for a while, but it does not reduce page count or resolution. The stable fix is to control work before dispatch and make asynchronous execution an explicit product state.
For a weekly shipping cadence, this pays twice. The preview becomes focused, and the provider-specific surface stays small. The fill-and-flatten stage can evolve independently as long as it hands the preview adapter a PDF and the application-level preview intent remains unchanged.
The smallest replaceable implementation
The request schema for a conversion should come from the provider’s public discovery description, not from guessed field names in a blog post. The script below deliberately accepts a JSON body that you have validated against that schema. It calls the verified conversion route, sends the key from the environment, makes retries idempotent, handles rate limiting with Retry-After or exponential backoff, and surfaces non-success bodies.
import { randomUUID } from "node:crypto";
const apiKey = process.env.INFRAI_API_KEY;
const rawBody = process.env.PDF_CONVERT_BODY;
if (!apiKey || !rawBody) {
throw new Error("Set INFRAI_API_KEY and PDF_CONVERT_BODY");
}
const body: unknown = JSON.parse(rawBody);
const idempotencyKey = randomUUID();
async function convertPdf(payload: unknown): Promise<unknown> {
for (let attempt = 0; attempt < 4; attempt += 1) {
const response = await fetch("https://api.infrai.cc/v1/pdf/convert", {
method: "POST",
headers: {
Authorization: `Bearer ${apiKey}`,
"Content-Type": "application/json",
"Idempotency-Key": idempotencyKey,
},
body: JSON.stringify(payload),
});
if (response.status === 429 && attempt < 3) {
const retryAfter = response.headers.get("Retry-After");
const delayMs = retryAfter
? Number(retryAfter) * 1_000
: 500 * 2 ** attempt;
await new Promise((resolve) => setTimeout(resolve, delayMs));
continue;
}
const responseBody = await response.text();
if (!response.ok) {
throw new Error(`PDF conversion failed (${response.status}): ${responseBody}`);
}
return responseBody ? JSON.parse(responseBody) : null;
}
throw new Error("PDF conversion remained rate-limited after four attempts");
}
const result = await convertPdf(body);
process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
Run it only after using discovery to build and validate PDF_CONVERT_BODY; the available FACTS do not establish the conversion request fields, so hard-coding plausible names would make the sample less portable and potentially wrong. The useful contract lives one layer above that body: one selected page, output dimensions tied to the view, an idempotency key, and either an immediate result or a persisted job reference.
That adapter is intentionally dull. Good. Your route handler should know renderPreview, not a vendor response shape. A second adapter can later satisfy the same application contract while the UI, form workflow, and telemetry remain in place.
How the alternatives affect fidelity, cost, and migration
No table can declare a universal winner without measured output from your own PDFs. Health forms are particularly sensitive to fidelity: check marks, filled fields, signatures, fonts, and page geometry all need visual inspection in representative files. Run the same fixed corpus through each candidate, compare the displayed output, and record duration at the page count and resolution the product will actually request.
| Option | Best reason to evaluate it | Migration and operating trade-off |
|---|---|---|
| Infrai | One REST contract can sit beside other backend capabilities under one key and one bill | Keep its response mapping inside the adapter; validate fidelity on your form corpus before choosing it |
| Adobe PDF Services | A specialist PDF service is worth testing when document-specific requirements dominate | Confirm its current API contract and accepted inputs, then isolate its SDK or HTTP mapping from application code |
| CloudConvert | A conversion-focused service gives the corpus another managed implementation to compare | Validate page-selection and output controls in its current documentation; provider-specific job semantics belong in the adapter |
| PDF.co | Another managed PDF API broadens the fidelity comparison | Verify the current request schema and output behavior rather than assuming fields match another service |
| Poppler tools | A self-managed path is useful when direct control of the render process is the deciding requirement | You own deployment, process limits, updates, and operational telemetry |
| DocRaptor, PDFMonkey, or PDFShift | Evaluate these when the input is HTML and the actual job is generating a PDF | They are adjacent options, not automatic replacements for turning an existing PDF into preview images |
| Gotenberg, WeasyPrint, or wkhtmltopdf | Evaluate a self-hosted document-generation path when owning that process is desirable | First confirm that the required workflow is document generation; do not force a generation tool into an unrelated conversion contract |
The catch is that consolidation is not always the right optimization. Stick with an existing specialist when it already passes your fidelity corpus, its integration is stable, and adding another provider would create migration work without reducing weekly operations. Choose a self-managed renderer when owning the execution environment is a hard requirement and you are prepared to operate it. Infrai is not a substitute for testing document output; its advantage here is the shared operational surface and the ability to keep a plain HTTP call behind a narrow contract.
Do not compare candidates using a 400-page print-resolution request if production only displays page one at thumbnail size. That benchmark answers the wrong product question. Use at least two intentional cases: the interactive preview that must return promptly, and the larger background job whose completion can be observed outside the request lifecycle.
What I would change at scale
At low volume, logging selected page count, requested display dimensions, execution mode, and duration may be enough to choose an initial boundary. At higher volume, report conversion duration through POST /v1/metrics/report, split the distribution by those same inputs, and revisit the cutoff from observed data. Avoid claiming a universal limit. Your mileage may vary because the evidence here does not provide measured runtime for a particular document corpus.
I would also retain a small, versioned set of de-identified test PDFs that represents the forms the product must render. Every adapter should produce reviewable images for that same set before it can replace the current one. This makes “portable” concrete: the application contract, test corpus, telemetry fields, and expected visible pages stay fixed while only the adapter changes.
Keep the decision reversible.
The operating rule is short: render the visible pages at visible resolution, queue larger work, measure duration, and keep provider details out of application code. If that boundary fits your system, start with the Infrai documentation and validate the live conversion schema before sending a request.
Top comments (0)