The failure that matters in a document translation integration is not the one that raises an error — it is the one returning
200 OK with a document that is quietly incomplete. A file over the size ceiling should be rejected cleanly with a machine-readable code, not truncated at page ninety. A password-protected PDF, a .doc renamed to .docx, a scanned agreement with no text layer and a corrupt archive should each produce a distinct failure. Establish what your vendor does by sending deliberately broken files during evaluation, because a client's document will find every boundary you did not test.
This guide walks the boundary conditions in the order they tend to appear in production, and ends with a poison-file suite worth keeping in your test pipeline.
Real Client Files Are Not Sample Files
Vendor sample documents are clean, recent, and produced by the vendor. Client files are not. They are twenty-year-old contracts scanned at an angle, PDFs exported by a document management system that died in 2014, spreadsheets with a hundred and forty tabs, and a .docx that is a Word 97 binary someone renamed because the upload form rejected the original extension.
That population produces a long tail, and the tail is where integrations break. A pipeline handling ninety-eight percent of files perfectly still fails weekly at data-room volume, and each failure lands on someone who has to work out what happened.
The design goal is not to process everything. It is that every file either succeeds completely or fails in a way your system can name, route and explain. Ambiguity is the enemy: "it came back but the last thirty pages are missing" costs far more than "rejected: exceeds page limit", because the first is discovered by a reader and the second by a queue.
Ceilings Are Measured in More Than One Dimension
"Maximum file size" is usually several limits wearing one label, and they bind at different times. Ask which of these exist and what each is measured against.
Bytes on the wire, which for compressed formats is not the same as content volume — a 4 MB DOCX can unpack to far more. Page count, which is what actually constrains a PDF. Character or word count, which is what constrains a text-heavy file with few pages. Embedded image volume, which is what makes a scanned document large without containing much text. Sheet, slide or tab count for spreadsheets and decks, where a workbook can be small on disk and enormous in cells.
Then the operational questions: is the limit per file or per request, does a batch carry its own aggregate ceiling, and is resumable upload supported for large files on a poor connection? A ceiling discovered through a timeout mid-upload on a Friday evening is a ceiling learned expensively.
Rejection Is Fine, Truncation Is Not
The behaviour to establish before anything else: what happens when a file exceeds a limit.
A clean rejection is a good outcome. An HTTP error with a specific code — one that names the limit and the observed value — lets your pipeline route the document to a split-and-resubmit path or to a human, and lets you tell the requester precisely why.
Truncation is the bad outcome, and it is not hypothetical. A service that processes what fits and returns a well-formed document containing the first portion produces a file that opens correctly, looks professional, and is missing the schedules. Nobody notices until someone looks for clause 27.
Defend against it mechanically. After every job, compare structural counts between source and output: pages, paragraphs, tables, footnotes, and the highest clause number present. A mismatch is a hard failure regardless of what the API returned. This is the same check that catches silent renumbering in format-critical output, and it should run on every document rather than the ones someone happens to read.
Declared File Types, Detected File Types, and the Gap Between
Extensions lie. Users rename files to get past upload validation, export tools write the wrong extension, and email clients mangle attachments in transit.
The common cases are specific. A Word 97–2003 binary renamed .docx, which fails the moment anything tries to open it as an Office Open XML ZIP package. An RTF file named .doc, which many tools tolerate and some do not. A PDF that is a thin wrapper around a single JPEG per page. A macro-enabled .docm where a .docx was expected. A CSV named .xlsx.
Detect type yourself, from content rather than filename — the magic bytes tell you what a file actually is. Then ask the vendor two things: what happens when declared and real type disagree, and is the supported-type list checked against detected type or extension? A service that accepts a mislabelled file and produces partial output is worse than one refusing it. Confirm too which formats are supported end to end rather than converted internally to something lossier on the way through.
Protected, Restricted and Corrupt Files
Three distinct conditions that are frequently collapsed into one unhelpful error.
Password-protected. PDFs carry two kinds — a user password that blocks opening, and an owner password that permits opening but restricts extraction. The second is the awkward one: the file opens fine in a viewer while the API may refuse it or silently extract nothing. Establish which. If your workflow supplies passwords, ask how they are transmitted, logged and retained — and never write one into a job record that lives in your audit store.
Rights-managed. Office files with information-rights protection are encrypted and typically unreadable outside the tenant. These belong in a routing rule, not an error queue.
Corrupt. A truncated ZIP container, a PDF with a broken cross-reference table, a file that failed halfway through a download. These need a different code from unsupported types, because the fix differs: re-fetch the source rather than convert it.
Ask for a distinct machine-readable error class per condition. "Cannot process file" tells your triage logic nothing and forces a human to open every failure.
The OCR Boundary, and Documents That Straddle It
A scanned page contains no text — only an image of text. Submit an image-only PDF to a service without OCR and the honest outcome is empty output; the dishonest one is a document that looks translated because a stray text layer of page numbers came through.
Ask whether OCR is included, whether it runs automatically or on request, and whether the result is a rebuilt document or a text extract. Then ask about mixed documents, more common in legal work than fully scanned ones: a born-digital agreement whose execution page and two exhibits are scanned inserts. A per-file OCR flag handles that badly.
Measure it yourself. Compute the ratio of extractable characters to page count before submission and route anything below a threshold to an OCR path. Recognition errors compound — a misread digit in a payment term survives translation looking entirely plausible — so scanned material warrants review of the kind ISO 18587 describes. Translators in this r/TranslationStudies thread on scanned PDFs are blunt about the cleanup involved.
Partial Failure Is the Normal Outcome for a Batch
Submit four hundred documents and some will fail. That is not an incident; it is arithmetic. What matters is whether your integration treats a batch as atomic when the vendor does not, or as independent when the vendor does not.
Establish the semantics explicitly. Does a batch containing three unprocessable files complete with three failures recorded, or does the whole submission fail? Is per-file status exposed while the batch runs? Can you retrieve finished outputs before the stragglers complete? Can you resubmit only the failures, keeping the batch identity intact for reporting?
Then reconcile by manifest. Record every file you intended to submit and assert at the end that each is in a terminal state — succeeded with an output, or failed with a reason. Files in neither category are the ones that vanish, and at data-room scale nobody notices three missing documents out of four hundred until diligence closes.
Error Responses You Can Actually Route On
Push the vendor on error design, because it determines how much of your failure handling is automatic and how much is a person reading a spreadsheet.
What you want per failure: a stable machine-readable code rather than prose, a clear retryable-versus-permanent distinction, the offending value where one exists, and the file identifier when the failure is inside a batch. Retryability is the load-bearing one — a transient capacity failure and a corrupt file both stop the job, but retrying the first is correct and retrying the second burns quota forever.
Map each code to a route: retry with backoff, split and resubmit, send to OCR, request the source again, or escalate to a named person with the reason attached. Anything unmapped goes to a queue someone actually watches. Every failure having an owner and a next action is what separates an integration that scales to contract volumes from one accumulating unexplained files.
A Poison-File Suite Worth Keeping
Build the folder once, run it before go-live and after every vendor or version change. Eight files cover most of the territory.
A file comfortably over the largest published ceiling.
A file just under it, to confirm the boundary is where it is documented.
A Word binary renamed
.docx.A password-protected PDF, and separately one with an owner password only.
A deliberately truncated DOCX, cut mid-archive.
A fully scanned, image-only PDF.
A mixed document with three scanned pages inside a digital file.
A batch of twenty containing three of the above.
For each, record what came back: status code, error class, whether output was produced, and whether structural counts matched. That table is a better vendor comparison than any feature list, and it takes an afternoon — considerably less than the afternoon spent explaining a truncated agreement to a client.
Sources and Further Reading
Advice on translating scanned PDFs — translators describing what image-only source material costs in practice
Related Reading
Choosing a Document Translation API for Automated Legal Workflows
Designing for Burst Throughput in Batch Document Translation
Last reviewed 24 August 2026 by the Bluente document engineering team, who build and test the pipeline described here. We update these guides when the underlying standards, regulations or file formats change.
Find the boundaries on your schedule, not a client's. Try BluTranslate free.