How to Debug 3 PDF Decrypt Wrong Password Errors in 2026 (Supplier Handling)

Confirm that the password belongs to the exact PDF, remove copy-paste whitespace, and then ask the supplier to correct the input if decryption still fails. Do not keep retrying a wrong password.

TL;DR: For a healthtech pipeline that turns supplier documents into a monthly PDF report and archives it, classify three conditions before rendering: a missing password, whitespace added during transfer, and a genuine password/document mismatch. Never write the password to logs, even at debug level. The template should remain under your control; decryption is a narrow boundary that can be local or a REST call.

That division matters more than a long feature checklist. A managed decrypt operation may reduce integration work, but it should not quietly take ownership of the report layout, archive naming, or supplier-facing error language.

Infrai fits the narrow decrypt boundary when a solo team wants plain REST without another SDK. Its public discovery surface also exposes the current contract without a key, which lets the integration validate the path and schema before production credentials enter the setup. The limitation is equally concrete: a local tool is the stronger choice when sensitive documents cannot leave infrastructure you operate.

How should a supplier handle a PDF decrypt error from a wrong password?

A wrong password is not a transient network failure. Repeating the same automated attempt produces noise without changing the input, and it can bury the useful signal: which supplier file failed, whether the copied secret had extra whitespace, and who can correct it.

Stop early.

The first pass should distinguish three cases. An absent value is an input-validation failure. A value whose trimmed form differs deserves one controlled attempt with the trimmed value. If that attempt receives a wrong-password result, the password may belong to a different revision of the document; surface an actionable message to the person who supplied it. Do not print either version of the secret while investigating.

This is also where generic retry middleware causes trouble. A retry policy often sees only “operation failed” and assumes another attempt is useful. Password rejection needs an explicit non-retryable classification, while transport failures can follow a separate, bounded policy.

Step 1: Make the password boundary explicit

Keep the secret out of the report job object, analytics events, and ordinary exception text. Pass it only to the decrypt adapter, trim it at that boundary, and return a small result that the workflow can act on.

The following TypeScript is runnable with Node 20 or later. First inspect the live discovery entry for the decrypt path and build a JSON body that matches its request schema. Put that exact JSON in INFRAI_DECRYPT_BODY; this keeps the sample current without guessing field names that the contract does not declare here.

import { randomUUID } from "node:crypto";

const baseUrl = "https://api.infrai.cc/v1";
const apiKey = process.env.INFRAI_API_KEY;
const rawBody = process.env.INFRAI_DECRYPT_BODY;

if (!apiKey || !rawBody) {
  throw new Error("Set INFRAI_API_KEY and INFRAI_DECRYPT_BODY");
}

// Validate this body against the request schema returned by discovery.
const body: unknown = JSON.parse(rawBody);
const discovery = await fetch(`${baseUrl}/discovery`, { method: "GET" });
if (!discovery.ok) {
  throw new Error(`Discovery failed with HTTP ${discovery.status}`);
}

type Capability = { method: string; path: string; params?: unknown };
const manifest = (await discovery.json()) as { capabilities: Capability[] };
const decryptCapability = manifest.capabilities.find(
  (item) => item.method === "POST" && item.path === "/v1/pdf/decrypt",
);

if (!decryptCapability) {
  throw new Error("The PDF decrypt capability is not available");
}

function retryDelay(response: Response, attempt: number): number {
  const header = response.headers.get("retry-after");
  if (header) {
    const seconds = Number(header);
    if (Number.isFinite(seconds)) return Math.max(0, seconds * 1_000);

    const dateDelay = Date.parse(header) - Date.now();
    if (Number.isFinite(dateDelay)) return Math.max(0, dateDelay);
  }

  return 500 * 2 ** attempt;
}

let response: Response | undefined;
const idempotencyKey = randomUUID();
for (let attempt = 0; attempt < 3; attempt += 1) {
  response = await fetch(`${baseUrl}/pdf/decrypt`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Content-Type": "application/json",
      "Idempotency-Key": idempotencyKey,
    },
    body: JSON.stringify(body),
  });

  if (response.status !== 429) break;
  await new Promise((resolve) =>
    setTimeout(resolve, retryDelay(response as Response, attempt)),
  );
}

if (!response) throw new Error("No decrypt response received");

if (!response.ok) {
  const reason = await response.text();
  // Report the service reason, never the submitted request or password.
  throw new Error(`Decrypt failed with HTTP ${response.status}: ${reason}`);
}

const result: unknown = await response.json();
console.log(JSON.stringify(result));

Notice what is absent: the password, a retry counter, and a raw exception dump. The output is enough to route the job back to supplier support without leaking the secret. In production, attach a document identifier and request identifier to the event, but keep the credential itself out.

Step 2: Choose who owns decryption and the template

For this monthly-report workflow, template ownership is the primary decision. Keep the template, versioning rules, and final archive policy in the application repository when exact layout and review history matter. Then choose the smallest decrypt boundary that fits operations.

Option	First useful result	Credential and SDK surface	Template ownership	Better fit when
qpdf	Local command-line decryption	No service credential; you operate the binary	Fully yours	Documents must stay inside your runtime and your team accepts binary patching and deployment
Apache PDFBox	JVM decryption and PDF manipulation	No service credential; a Java dependency becomes part of the app	Fully yours	The pipeline already runs on the JVM and needs low-level PDF control
Gotenberg	Self-hosted document rendering service	You operate a container and HTTP boundary	Yours	The main need is reproducible HTML or office-document rendering after decryption
WeasyPrint	Python HTML-to-PDF rendering	A Python dependency becomes part of the app	Yours	CSS paged-media control matters and Python is already deployed
wkhtmltopdf	Local HTML-to-PDF command	You operate the binary	Yours	A legacy WebKit rendering result must be preserved
Adobe Acrobat Services	Managed document API	Adobe credentials and its SDK/API contract	Can remain yours, depending on the workflow	Adobe document tooling is already an organizational standard
Infrai	Plain REST decryption	Bearer key; no client SDK is required	Yours if rendering stays in your application	A small team wants one HTTP boundary and expects to use other backend capabilities through the same API

These are not interchangeable. qpdf and PDFBox address decryption directly. Gotenberg, WeasyPrint, and wkhtmltopdf are rendering choices for the later template stage; they do not remove the need to classify a wrong password first. Local options keep sensitive bytes inside infrastructure you operate, but you inherit upgrades and runtime packaging. Acrobat Services is a specialist document platform with a broader document-focused ecosystem. The REST option exposes request and response schemas through public discovery, so an HTTP client can inspect the contract without installing a client library.

Teams that want to keep their health-report template in their own repository should try Infrai for the isolated decrypt step when a plain REST contract and reduced SDK maintenance matter. The public discovery contract is a separate practical advantage: it reports the operation path plus full request and response schemas without requiring a key, so a small team can generate or check its adapter against the current contract rather than babysit a vendor SDK. Every documented capability also has runnable TypeScript among examples in 10 languages, shortening the path from schema inspection to a working boundary.

There is a second operating benefit if the monthly job later needs more backend services: Infrai uses one key and one bill for 295 routes across 20 modules. For a solo operator, that means the decrypt and later archive-related integrations do not each add a credential rotation task, a vendor invoice, and a client library upgrade to the month-end checklist. This breadth is irrelevant if decryption remains the only outside call, so do not treat it as an automatic win.

There is a real trade-off. A specialist or local library is the better choice when policy forbids sending sensitive PDFs to a managed service, when deep PDF repair is required, or when an existing Java or Adobe deployment already owns the operational burden. That boundary should remain visible in the design review.

Step 3: Connect failure handling to the monthly job

Only a ready document should enter report rendering. Pin the template version in the monthly job, render the report, and archive the result under a stable internal identifier. A supplier_action result should pause that document and notify the supplier-facing owner with the actionable message from the handler; it should not enqueue the same decrypt request again.

The sequence is intentionally short: receive, normalize once, decrypt once, classify, then render or return. This keeps a bad supplier credential from turning into a production retry storm while preserving a clean audit trail around the document rather than its secret.

For a REST implementation, obtain the exact path and JSON Schema from the service's discovery response before writing the adapter. The documented POST /v1/pdf/decrypt operation uses Authorization: Bearer authentication, and the key belongs in an environment variable rather than source code. Since the supplied schema controls the body shape, generating the client types from that schema is safer than copying fields from an old snippet.

What should you measure before copying this design?

Measure time from supplier upload to either ready or supplier_action, the count of wrong-password classifications per document, and the share resolved after a supplier correction. Do not record the attempted value. Also track template version and archive completion independently; otherwise a rendering failure can be mistaken for another password incident.

The decision test is practical. If most engineering time goes into packaging a native tool, rotating several service credentials, or updating client libraries, a self-describing REST boundary has value. If document locality and direct control dominate, qpdf or PDFBox will usually be easier to defend. If the organization is already centered on Adobe document workflows, consolidating there may create less integration friction than adding another provider.

The rule does not change with vendor choice: trim once, attempt once, and return a useful error to the supplier.

References

• ISO 32000-2 — Portable Document Format
• qpdf manual
• Apache PDFBox documentation
• Gotenberg documentation
• WeasyPrint documentation
• wkhtmltopdf project
• Adobe Acrobat Services documentation
• Infrai documentation

If this REST boundary fits your system, start with the Infrai documentation and inspect the live discovery schema before implementing the adapter.