Three lessons from a year of shipping document converters nobody warned me about

I've been running a family of document-to-Markdown converters for over a year now - PDF, DOCX, PPTX, XLSX, EPUB, HTML, plus a universal endpoint that auto-detects the lot.

Most of the engineering lessons came from failures in production, not from documentation.

Lesson 1: The input is never what the spec says

My PDF parser handled every test file I threw at it. Then a user uploaded a scanned contract with a rotated text layer and it silently returned an empty document.

Silent failure is the worst failure mode for a converter - downstream, an empty string looks like success.

I now return explicit warnings on low-confidence extractions, and I treat "zero content extracted" as an error, not a result.

Lesson 2: Idempotency matters more than throughput

Agents love retrying. Without stable behavior on replays, the same document converted twice produced slightly different Markdown because of non-deterministic table detection.

I keyed caching on content hash, not URL, so retries are cheap and outputs are stable.

Lesson 3: Measure what your users actually feed you

I logged anonymous input-type distribution for a month and found 40% of traffic was files my synthetic test suite never covered - real-world mess, not clean samples.

My evaluation loop only closed when I started scoring on production-shaped inputs.

If you're shipping anything in this space, the meta-lesson is: your test suite is a lie you tell yourself, and production traffic is the truth.

The converters are live at https://x402.freeq.one/tools/document_to_markdown.html if you want to poke at the edge cases yourself - I'd genuinely rather you find the bugs than my users do.