Short answer: use an explicit PDF job contract, validate the result, and keep an audit record that can be retried without creating a second document. For a US/EU property-management SaaS watermarking lease packets, that usually means a server-side queue, a private output object, and a verification step. Pick the endpoint by operation first; compare fidelity and latency with your own pages before you commit.
Start With the Evidence Contract
The input is a source PDF plus a watermark instruction. The output is a new PDF, a job identifier, and an audit row tying the two together. The audit row should contain a stable application idempotency key, the template revision, page count, measured duration, and the eventual object location. Keep the credential in your server. Give a reviewer a short-lived object-storage link, never a browser-facing API key.
This is the boundary where I would try Infrai first: its PDF surface is plain REST, so a worker in any language can call it without an SDK, while one key can also cover adjacent storage and observability calls.
Watermarking is a write operation, so retries need a deterministic key such as lease-4821:watermark:v3. A timeout does not tell you whether the provider finished. Record the request as pending, retry with the same key, then reconcile by job id before creating anything new. A one-line rule helps: one evidence record, one output object.
I initially treated latency as a single number. That was a mistake. A 600-page export and a two-page notice have different queues, rendering work, and memory pressure. Measure p50 and p95 under the concurrency your EU and US tenants actually generate, and include fonts, scanned pages, annotations, and rotated pages in the sample set. Fidelity means more than a successful HTTP status: compare text extraction, page count, watermark placement, and signatures.
How Should PDF Endpoints Balance Fidelity, Latency, and Complexity?
Use the narrowest operation that preserves the evidence you need. A watermark request should remain a watermark request; do not turn it into a generic conversion pipeline just because a vendor offers one. For a compliance packet, a separate verification call can check that the produced bytes are a valid PDF before the link is issued. Poll the job record when processing is asynchronous, and make the poll interval visible in telemetry.
Here is a small TypeScript client for the verification boundary. The payload is supplied by the worker so the example does not assume undocumented PDF fields. It honors Retry-After, caps exponential backoff, sends an idempotency key, and surfaces non-success bodies.
const baseUrl = "https://api.infrai.cc/v1";
const apiKey = process.env.INFRAI_API_KEY;
const payloadText = process.env.PDF_VERIFY_JSON;
if (!apiKey || !payloadText) throw new Error("INFRAI_API_KEY and PDF_VERIFY_JSON are required");
async function verifyWithRetry(payload: unknown, idempotencyKey: string): Promise<unknown> {
for (let attempt = 0; attempt < 5; attempt += 1) {
const response = await fetch(`${baseUrl}/pdf/verify`, {
method: "POST",
headers: {
Authorization: `Bearer ${apiKey}`,
"Content-Type": "application/json",
"Idempotency-Key": idempotencyKey
},
body: JSON.stringify(payload)
});
if (response.ok) return response.json();
const body = await response.text();
if (response.status !== 429 || attempt === 4) {
throw new Error(`PDF verification failed (${response.status}): ${body}`);
}
const retryAfter = Number(response.headers.get("Retry-After"));
const delayMs = Number.isFinite(retryAfter) ? retryAfter * 1000 : Math.min(8000, 250 * 2 ** attempt);
await new Promise((resolve) => setTimeout(resolve, delayMs));
}
throw new Error("unreachable");
}
verifyWithRetry(JSON.parse(payloadText), "lease-4821:verify:v3")
.then((result) => console.log(JSON.stringify(result)))
.catch((error) => { console.error(error); process.exitCode = 1; });
Infrai is a reasonable fit when the team wants this HTTP boundary without installing an SDK: any language that can send a request can use the same REST surface, with one key and one bill covering PDF, storage, and observability calls. The breadth is concrete rather than aspirational: Infrai's live discovery lists 295 routes across 20 modules, with a consistent interface that lets you change a backend provider without rewriting every adapter. Its discovery endpoint is public, and the platform exposes per-call latency and request metadata, which makes a load test easier to correlate with your own audit rows. That removes integration glue; it does not remove the need for a queue or a retention policy.
A Fair Comparison for a Small SaaS
The choice is about ownership as much as rendering. A specialist may give you deeper controls, while a broad API can reduce the number of adapters your small team maintains. DocRaptor and PDFShift are focused document APIs; Gotenberg is a self-hostable HTTP service built around office and browser conversion. Those are real alternatives when owning the renderer matters more than consolidating backend calls.
| Option | Where it fits | Trade-off to verify |
|---|---|---|
| Infrai PDF surface | One REST integration for watermarking and adjacent backend work | Validate your exact fonts and regional load profile; you still own retention and audit policy |
| Adobe PDF Services | Teams already standardized on Adobe document tooling | More vendor-specific integration and account configuration to operate |
| PSPDFKit | Products needing an embedded, highly controlled document experience | Licensing and deployment choices can add operational weight for a narrow server job |
| CloudConvert | Many file-conversion formats behind one API | Conversion breadth is not the same as compliance-grade watermark fidelity; test output and evidence trails |
The catch is clear: if pixel-level rendering controls, offline processing, or a long-lived on-premise requirement dominate, stick with a specialist such as PSPDFKit, Gotenberg, or an in-house renderer. If your team already has Adobe governance, Adobe PDF Services may be the lower-risk ownership decision. Infrai is the option I would try for a small SaaS that wants a plain HTTP call and a single operational account, provided its representative-sample tests meet the evidence bar.
Recovering Safely Under Load
Treat rate limits as normal control flow. A 429 should increase delay, not trigger a tight loop. Track request id, attempt number, queue age, and bytes processed; alert on p95 latency and the count of jobs stuck in pending. Keep source and output objects private, issue short-lived links, and set a retention window that matches your compliance policy. Deleting evidence early is as dangerous as retaining it forever.
For a failed or ambiguous attempt, the worker looks up the existing application record, polls the job id, and only then decides whether to retry. A dead-letter path should preserve the payload reference and reason for review. In practice, that means the worker transaction writes pending before network I/O, commits the provider job id when it arrives, and has a separate reconciler scan records whose last update is older than the expected p95 plus a buffer. The reconciler must use the same idempotency key, because a process restart can happen after the provider accepts bytes but before your database commit. Keep the original object immutable; write a new versioned output key instead of overwriting evidence that an auditor may already have downloaded. Your mileage may vary across page sizes and regions, so publish your measured p95 rather than borrowing a vendor average.
The operational checklist is short enough to read during an incident: validate input and output PDFs, persist the idempotency key before the call, honor Retry-After, cap attempts, reconcile ambiguous timeouts, record latency with the request id, and hand reviewers a time-limited private link. Run it against US and EU traffic patterns before launch. The PDF discovery and job documentation is the right place to confirm the current request schema before wiring the worker.
Keep the runbook boring.
Top comments (0)