PDFs - use StartDocumentAnalysis not AnalyzeDocument

Not specified by the original author.

TL;DR

For PDFs use the async API: StartDocumentAnalysis to kick off the job, then poll GetDocumentAnalysis until it succeeds. UnsupportedDocumentException on a PDF means you called the sync AnalyzeDocument API, which only takes PNG or JPG.

Steps

1. UnsupportedDocumentException on a PDF means you called the sync AnalyzeDocument API, which only takes PNG or JPG. For PDFs use the async API: StartDocumentAnalysis to kick off the job, then poll GetDocumentAnalysis until it succeeds. The sync and async APIs look similar but accept different inputs - any PDF, TIFF, or multi-page document must go through the Start/Get async pair.

When to use

You are seeing this: UnsupportedDocumentException on a PDF means you called the sync AnalyzeDocument API, which only takes PNG or JPG. Use this skill when you run into "UnsupportedDocumentException on PDFs - use StartDocumentAnalysis, not AnalyzeDocument".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

Source: Stack Overflow 60501332 (accepted answer, 13 votes): calling AnalyzeDocument on a PDF with boto3 threw UnsupportedDocumentException. The accepted answer nails it: AnalyzeDocument is the synchronous API and only accepts PNG or JPG images.

Verified resolution: UnsupportedDocumentException on a PDF means you called the sync AnalyzeDocument API, which only takes PNG or JPG. For PDFs use the async API: StartDocumentAnalysis to kick off the job, then poll GetDocumentAnalysis until it succeeds. The sync and async APIs look similar but accept different inputs - any PDF, TIFF, or multi-page document must go through the Start/Get async pair.

Source URL: https://stackoverflow.com/questions/60501332

Not specified by the original author.

Mathpix: image OCR is sync, document conversion is async with polling

TL;DR

Route images to the v3/text image endpoint and PDFs to the async document flow, then poll status until the conversion completes before fetching output. If your Mathpix call fails on a PDF, check which endpoint you hit first. For batch pipelines, use the confidence thresholds to catch bad OCR instead of trusting every result.

Use this when you run into the situation in the title.

When not to use this skill: unrelated tasks. It covers only the procedure above.

Compatibility

The steps above apply to the commands named in them. This skill does not pin a version, so if a flag looks different on your machine, check your installed version's docs first.

Details

Context: Repo README (mathpix/mpxpy, the official Python client): documents that single-image OCR and document conversion are two different flows. Images go to v3/text synchronously, but PDF and document conversion is async: submit the file, then poll for completion before downloading outputs in MMD, Markdown, DOCX, LaTeX, or HTML. Gotcha that trips agents: POSTing a PDF to the image endpoint fails. The README also documents an isasync flag for non-interactive image requests and confidencethreshold knobs that raise errors on low-confidence OCR instead of silently returning junk.

Source: Repo README (mathpix/mpxpy, the official Python client): documents that single-image OCR and document conversion are two different flows. Images go to v3/text synchronously, but PDF and document conversion is async: submit the file, then poll for completion before downloading outputs in MMD, Markdown, DOCX, LaTeX, or HTML. Gotcha that trips agents: POSTing a PDF to the image endpoint fails. The README also documents an isasync flag for non-interactive image requests and confidencethreshold knobs that raise errors on low-confidence OCR instead of silently returning junk.

Verified resolution: Route images to the v3/text image endpoint and PDFs to the async document flow, then poll status until the conversion completes before fetching output. If your Mathpix call fails on a PDF, check which endpoint you hit first. For batch pipelines, use the confidence thresholds to catch bad OCR instead of trusting every result.

Source URL: https://github.com/mathpix/mpxpy/blob/HEAD/README.md

Not specified by the original author.

TL;DR

Check the limits before anything else. For large PDFs, uploading once and referencing by file_id keeps request payloads small and lets you reuse the document across calls. Query one section at a time with citations enabled so answers point at exact pages. Cross-section synthesis happens in a final pass over the per-section summaries, not in one giant request.

When to use

You are seeing this: Get large PDFs through the API without failed requests. Use this skill when you run into "Process large PDFs with the Files API and page budgeting".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Get large PDFs through the API without failed requests.

1. Check the limits before anything else. A request carrying a PDF must stay under 32 MB total payload and 600 pages per request, or 100 pages when the request's context window is under 1M tokens. Both limits cover the entire request payload, including any other content sent alongside the PDF.
2. Upload with the Files API and reference by fileid. For large PDFs, uploading once and referencing by fileid keeps request payloads small and lets you reuse the document across calls. This is the single biggest reliability win.
3. Budget pages against the context window, not the page cap. Dense PDFs (small fonts, complex tables, heavy graphics) fill the context window before reaching the page limit, and each page is processed as an image. Estimate pages per request from the window size and your output budget, then split the document into sections and process section by section.
4. Downsample embedded images for heavy pages. If requests fail before the page limit even via the Files API, the pages are too image-heavy: downsample embedded images and retry the section.
5. Ask section-sized questions. Query one section at a time with citations enabled so answers point at exact pages. Cross-section synthesis happens in a final pass over the per-section summaries, not in one giant request.
6. Combine with caching for repeat analysis. If you query the same document many times, put the fileid document block in the cached prefix with cachecontrol so later questions do not reprocess the PDF.

Claims verified against Anthropic's official docs (platform.claude.com) on 2026-09-26. Evidence URLs in public_references.