DocRaptor Error 422: Common Causes and Fixes

DocRaptor HTTP 422 means the input document has syntax errors that DocRaptor cannot process as expected. DocRaptor defines it this way in its HTTP Status Codes documentation. Start with the exact HTML or XML sent to the API and the error details in the response. A 422 is not the status DocRaptor assigns to an incorrect API key or a permission problem.

1. Confirm the status and inspect the error response

First distinguish a confirmed 422 from a neighboring API or access error. DocRaptor documents 400 for a bad request, 401 for an incorrect API key, and 403 for permission problems or too many simultaneous generation requests. Those statuses call for different diagnosis; do not try an API-key or concurrency fix for a confirmed 422 unless the response also shows a separate problem.

For synchronous generation, a generation error can be returned as an XML error message instead of the expected document bytes. For asynchronous jobs, inspect the job status response and its validation details. Save the response body and reproduce with the exact submitted input, not just a local file or browser preview. See the DocRaptor API overview.

2. Validate the exact input document

DocRaptor’s definition points to syntax in the input document. Check the exact string or URL content your application submitted. If the document is assembled from templates, data, or fragments, capture the final rendered HTML/XML immediately before the API call.

1. Log or save the final document payload safely, including the character encoding and the URL used if you submit a URL.
2. Run an HTML or XML validator appropriate to the document format. For XML or XHTML, check well-formedness, matching tags, quoted attributes, and entity escaping. For HTML, check malformed nesting, unclosed or accidentally truncated markup, and invalid characters.
3. Compare the saved payload with the version that fails. Look for conditional template output, missing data, unescaped user-provided values, and truncation during serialization or transport.
4. Reduce the document to a minimal failing case, then add sections back until the syntax issue is isolated.

A browser preview is useful for appearance but does not prove that the exact payload is syntactically valid or that it contains the same content as the request.

3. Check rendering configuration after syntax

Some configuration problems cause incorrect output rather than a universal 422. Keep that distinction clear: DocRaptor’s documented meaning for 422 is input syntax, while these settings are useful checks when the input is valid but rendering fails or differs from expectations.

Print media versus screen media

DocRaptor applies print media by default. If the document looks wrong because it relies on screen styles, set prince_options[media] = screen as described in the DocRaptor documentation. This can correct styling differences; it is not a general cure for malformed input.

JavaScript-driven content

JavaScript is disabled by default. If the source document depends on a client-side framework to produce its content, enable JavaScript using the documented option. For asynchronous rendering, signal completion with docraptorJavaScriptFinished() when the page is ready. Disable chart animation if it prevents charts from reaching a stable rendered state.

Character encoding and resource paths

Specify UTF-8 when needed, and make resource URLs absolute or provide a base URL so relative CSS, image, and font references resolve from the intended location. Check that the URL submitted to DocRaptor returns the document you expect, rather than a login page, an error page, or a different template output.

4. Investigate remote assets when configured as fatal

By default, many resource-download errors are ignored. If ignore_resource_errors is disabled, asset failures can fail generation. DocRaptor lists examples including HTTP 400 or 500 responses, DNS failures, unknown MIME types, timeouts, SSL problems, and rejected connections in its resource error documentation.

• Confirm each stylesheet, image, font, and other referenced asset is reachable from the conversion service.
• Check the resource response status, MIME type, TLS configuration, and whether the URL requires credentials or network access unavailable to the service.
• Review whether strict resource-error handling is required. If it is, fix the failing resource rather than silently relying on a missing asset.

Resource failures are a separate layer from document syntax. Investigate them when the response or configuration points to resource loading, rather than assuming every 422 is a network problem.

5. Troubleshooting by symptom

Symptom	Likely cause	What to do
HTTP 422	Syntax errors in the submitted input document	Inspect the exact final HTML/XML and the response details; validate and reduce to a minimal failing document.
HTTP 400	Bad API request	Check request structure and parameter names against the API documentation.
HTTP 401	Incorrect API key	Verify the key and how the request supplies it.
HTTP 403	Permission problem or too many simultaneous generation requests	Check account permissions and concurrency; do not treat it as a syntax diagnosis.
Response is XML instead of PDF bytes	Generation error response	Read and preserve the XML error details; the response may explain the failing input or generation step.
PDF styling differs from browser	Print media is active by default	If screen styling is intended, try prince_options[media] = screen.
Content rendered by a framework is missing	JavaScript is disabled by default or rendering finished too early	Enable JavaScript as documented and signal completion with docraptorJavaScriptFinished() when asynchronous work is done.
Images, CSS, or fonts fail to load	Invalid relative URL, inaccessible resource, or strict resource-error configuration	Use absolute URLs or a base URL; verify access and resource responses, and review ignore_resource_errors.

6. Escalate with a reproducible case

If the failure persists, provide the exact input, response details, relevant rendering options, and a minimal reproduction. DocRaptor’s dashboard Help Request shares document input, output, and logs with support; its support page also lists email and live chat. See DocRaptor Support. Remove secrets and sensitive personal data before sharing a reproduction.

7. Screenshot a page while diagnosing its source

If you also need a visual record of the source page while investigating a document, ScreenshotNeo is a website screenshot API and MCP server. It can capture a page as PNG, JPEG, WebP, or PDF. A screenshot can help compare what a browser displays with the HTML or URL being submitted; it does not diagnose or repair DocRaptor input syntax.

Or skip the browser setup

ScreenshotNeo takes a screenshot with one GET request. The example uses Stripe as the target URL; replace it with the page you need. See the API documentation for request options.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

• Cookie banners are accepted and removed before capture, along with known consent platforms, newsletter popups, and chat widgets; each cleanup step can be turned off.
• Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed. Responses include X-Page-Verdict and X-Billed headers.
• An MCP server gives AI agents tools to take screenshots, inspect page information, and capture PDFs.
• The Free plan includes 1,000 screenshots per month with no card. Paid plans start at $5 for 3,000 screenshots.

Sign up free for 1,000 screenshots a month, with no card required.

Performance, reliability, and cost considerations

For DocRaptor, keep troubleshooting evidence small and reproducible: a minimal input makes syntax faults easier to isolate, and the returned error details avoid repeated blind changes. JavaScript and remote assets add rendering dependencies, so enable them only as the document requires and verify that asynchronous work finishes. The supplied official material does not establish conversion timing, reliability rates, or per-document cost, so consult current DocRaptor account and documentation details for those figures.

For ScreenshotNeo, the stated billing rule is that only clean shots are billed; bot checks, CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing. Caching supports a TTL you choose. Its listed monthly tiers are Free (1,000), Starter ($5/3,000), Growth ($15/15,000), Pro ($39/60,000), Scale ($99/250,000), and Business ($249/1,000,000); yearly billing gives two months free, and every feature is on every plan. See the documentation for configuration and usage details.

FAQ

Does a 422 mean my API key is wrong?

No. DocRaptor documents 401 for an incorrect API key; 422 indicates input-document syntax errors.

Can changing print media fix a 422?

It can address an appearance mismatch when screen styling was intended. It is not the documented general fix for a 422 syntax error.

Should I always enable JavaScript?

No. It is disabled by default and is only needed when your document depends on script-generated content.