Troubleshoot Parsing

Use this section to troubleshoot issues encountered when calling the Parse API.

Error Response Format

Every API error returns a JSON body with two fields:

{
  "code": "unknown_model_version",
  "message": "Unknown model version 'dpt-2'. Available: dpt-3-pro-20260710, dpt-3-pro-latest, dpt-3-pro, dpt-3-verity-20260804-preview, dpt-3-verity-latest, dpt-3-verity."
}

The code field is a stable identifier you can branch on, such as validation_error, unknown_model_version, invalid_url, invalid_api_key, or rate_limit_exceeded. The message field is a human-readable description; treat its exact wording as variable. The error messages quoted on this page are message values.

Common Status Codes

These status codes are handled at the account and gateway level and can apply to any request.

Status Code	Name	Description	What to Do
401	Unauthorized	Missing or invalid API key.	Check that your `Authorization` header is present and contains a valid API key.
402	Payment Required	Your account does not have enough credits to complete processing.	If you have multiple accounts, make sure you’re using the correct API key. Add more credits to your account.
429	Too Many Requests	A rate limit rejected the request: either the limit is temporarily exhausted, or the document is too large for the tier.	The error message states which case you hit and the fix. See Status 429.
502	Bad Gateway	A transient infrastructure error interrupted the request.	Retry with exponential backoff. A synchronous request that fails to deliver a result is not billed.
503	Service Unavailable	The service is temporarily unavailable.	Retry with exponential backoff. If the error persists, contact support@landing.ai.

Parse Status Codes

Status Code	Name	Description	What to Do
200	Success	Document parsed successfully and returned immediately.	Continue with normal operations.
206	Partial Content	Document parsed, but at least one page (and not all pages) failed during processing.	Review the `failed_pages` field in the metadata. See Status 206.
422	Unprocessable Entity	Input validation failed, including an unknown model version, an invalid `document_url`, an out-of-range `pages` selection, or a document over the size limits.	Review your request parameters. See Status 422.
500	Internal Server Error	All pages failed to process.	Retry. If the issue persists, contact support@landing.ai. See Status 500.
504	Gateway Timeout	Request processing exceeded the timeout limit (475 seconds).	Reduce the number of pages per request or use Parse Jobs. See Status 504.

Status 206: Partial Content

This response occurs when the document was parsed successfully but at least one page (and not all pages) failed during processing. The response includes:

A 206 status code.
Parsed content for the successful pages. Each successful page has a status of "ok" in structure.children.
A failed_pages array in metadata listing which pages failed (1-indexed).
A status of "failed", a reason, and a zero-length range on each failed page in structure.children.

Because the API returns at least partial results, the call consumes credits. What to do:

Review metadata.failed_pages to identify which pages failed.
Review the reason on each failed page in structure.children for details.
Check whether the failed pages are corrupted or have unusual formatting.
If the issue persists with specific pages, contact support@landing.ai.

For more on the response shape, see Parse API Response.

Status 422: Unprocessable Entity

This status code indicates input validation failures. Review the error message and adjust your request parameters.

Error: Unknown Model Version

This error occurs when the model form field specifies a version that is not registered. The error code is unknown_model_version. Error message:

Unknown model version '{version}'. Available: {versions}.

What to do:

Omit the model field to use the latest DPT-3 Pro snapshot by default.
Supply a valid version: a family alias such as dpt-3-pro-latest or dpt-3-verity, or a dated snapshot from Model Versions and Snapshots.

Error: Invalid document_url Scheme

This error occurs when the document_url uses a scheme other than http or https (for example, ftp:// or file://). Error message:

document_url scheme must be http or https, got '{scheme}'

What to do: Supply a document_url that begins with http:// or https://.

Error: document_url Missing Hostname

This error occurs when the document_url does not contain a hostname. Error message:

document_url missing hostname

What to do: Verify the URL is complete and properly formatted, including a hostname (for example, https://example.com/file.pdf).

Error: document_url Did Not Resolve

This error occurs when the document_url hostname cannot be resolved through DNS. Error message:

document_url hostname did not resolve: {hostname}

What to do:

Verify the hostname is spelled correctly.
Confirm the host is publicly reachable.

Error: document_url Resolves to a Non-Public IP

This error occurs when the document_url hostname resolves to a private, loopback, link-local, reserved, or multicast IP address. Only publicly reachable URLs are allowed. The error code is invalid_url. Error message:

document_url resolves to a non-public IP: {ip}

What to do: Host the document at a publicly accessible URL, or upload the file directly using the document parameter.

Error: document_url Returned a Redirect

This error occurs when the document_url responds with a redirect (301, 302, 303, 307, or 308). The server does not follow redirects; the URL must serve the file bytes directly. Error message:

document_url returned a redirect; supply the final URL directly.

What to do: Resolve the redirect yourself and supply the final destination URL that serves the file directly.

Error: document_url Fetch Failed

This error occurs when the URL passes validation but the file cannot be fetched: the server returns an error status, times out, or refuses the connection. Error message:

Failed to fetch document_url: HTTP {status}

Failed to fetch document_url: request timed out

Failed to fetch document_url: connection failed

What to do:

Verify the URL serves the file and is publicly reachable.
If the URL is presigned, confirm it has not expired.

Error: output_save_url Expired or Expires Too Soon

This error occurs when you create a job with an output_save_url whose presigned URL is already expired or does not stay valid long enough for the job to complete. The output is delivered when the job completes, so the URL must outlive the job: Parse Jobs requires at least 15 minutes of remaining validity plus 3 seconds per page. The error code is invalid_url. Error message:

output_save_url presigned URL expired {time} ago; sign a fresh URL valid for at least {required}

output_save_url presigned URL expires in {remaining}, but this request requires at least {required} of validity (the URL must outlive the job; it is used at completion, not at submit)

What to do:

Sign a fresh presigned URL with a longer validity and create the job again. The job is rejected before processing starts, so no credits are consumed.
For Azure SAS URLs, also confirm the token grants write (w) or create (c) permission. A URL without write access is rejected with a similar 422 error.
Sign delivery URLs with long-lived credentials. A URL signed with temporary session credentials can pass this check but still fail at delivery if the session expires before the job completes.

Error: Document Exceeds the Size Cap

This error occurs when the document exceeds the 50 MiB size limit. The limit applies whether you upload the file directly (document) or supply a URL (document_url). Error message:

document exceeds 50 MiB cap

document_url body exceeds 50 MiB cap

What to do:

Reduce the document size to 50 MiB or less.
Split larger documents into smaller files, or submit the document to Parse Jobs, which accepts documents up to 1 GiB. See Rate Limits for current size limits.

Error: Image Exceeds the Maximum Resolution

This error occurs when an image has more pixels than the maximum image resolution of 178,956,970 pixels (about 179 megapixels). The check runs on the image’s declared dimensions, so an oversized image is rejected even when its file size is under the 50 MiB cap. No credits are consumed. On Parse Jobs, the check runs after the job starts, so an oversized image fails the job instead of rejecting the creation request. The poll response reports a failed status, with the code ParseImageTooLarge and this message in the error field. See Failed Jobs. Error message:

image exceeds the maximum supported size of 178956970 pixels

What to do: Downscale the image below the resolution limit before uploading. Parsing accuracy does not benefit from resolutions this high, because pages are downscaled during processing anyway.

Error: Must Provide a Document

This error occurs when your request includes neither the document nor the document_url parameter. Error message:

One of `document` or `document_url` is required.

What to do: Add one of these parameters to your request:

Use the document parameter to upload a file.
Use the document_url parameter to provide a URL to a file.

Error: Cannot Provide Both document and document_url

This error occurs when both a file and a URL are provided in the same request. Error message:

Provide exactly one of `document` or `document_url`, not both.

What to do: Choose one input method and remove the other from your request.

Error: Page Numbers Must Be 1-Indexed

This error occurs when the options.pages selector includes 0 or a negative number. Page numbers are 1-indexed: 1 is the document’s first page. Error message:

pages: page numbers are 1-indexed (must be >= 1), got: [0]

What to do: Update the pages values to 1-indexed page numbers. For example, to parse the first and third pages, send {"pages": [1, 3]}.

Error: Pages Out of Range

This error occurs when the options.pages selector includes a page number beyond the document’s last page. A single out-of-range value rejects the whole request, even when the other values are valid. On Parse Jobs, the page count is not known when you create the job, so an out-of-range selection fails the job instead of rejecting the creation request. The poll response reports a failed status, with this message in error.message. See Failed Jobs. Error message:

pages out of range: {pages}; the document has {N} page(s)

What to do: Remove the out-of-range page numbers from the selection. To check a document’s length, read metadata.page_count from a parse of the full document.

Error: Empty File

This error occurs when the uploaded file contains no data. Error message:

Empty file ({filename}).

What to do: Upload a valid file that contains content.

Error: Unsupported or Unrecognized File Format

This error occurs when the file is not a supported PDF, image, or Office document. Spreadsheets (XLSX, CSV) and legacy binary Office files (DOC, PPT) are not supported. The format is detected from the file’s content, not its extension or Content-Type header. Error message:

Unsupported format: {format} ({filename}). Supported formats: PDF, PNG, JPEG, GIF, BMP, TIFF, WEBP, DOCX, PPTX, ODT, RTF.

Unrecognised file format ({filename}). Supported formats: PDF, PNG, JPEG, GIF, BMP, TIFF, WEBP, DOCX, PPTX, ODT, RTF.

What to do:

Convert your document to a supported format before uploading. See Supported File Types.
Verify the file is not corrupted by opening it in the appropriate application.

Error: Too Many Pages

This error occurs when a PDF exceeds the per-request page limit. The limit applies to both Parse and Parse Jobs. See Rate Limits. Error message:

document has {N} pages; the per-request limit is {limit}

What to do: Split the PDF into shorter PDFs and parse them separately. A document under the page limit can still exceed your priority tier’s per-minute rate limit; in that case the request returns a 429 error, and the fix is to submit the document as a standard tier job. See Rate Limits.

Error: Failed to Fetch document_url

This error occurs when the server cannot retrieve the file from the document_url. The URL returned an HTTP error status, or the request failed (for example, a connection or timeout error). Error message:

Failed to fetch document_url: HTTP {status}

document_url fetch failed: {error_type}

What to do:

Verify the URL is accessible and returns the file directly.
Check that the URL does not require authentication.
Confirm the host is reachable and responds within the timeout.

Error: Invalid options Value

This error occurs when the options form field is not valid JSON, when its contents fail validation, or when it contains a key the API does not recognize. Unknown keys are rejected at every nesting level, including the retired legacy options dpi, grounding, and blocks.<type>.caption. Error message:

options: invalid JSON: {details}

options.dpi: Extra inputs are not permitted

What to do:

Ensure options is a valid JSON object.
Remove any option key named in the message. If the key is a legacy option, use its replacement: blocks.<type>.markdown instead of blocks.<type>.caption, and atomic_grounding instead of grounding.parts. The dpi option has no replacement; coordinates are normalized.
Use 1-indexed page numbers in pages, and keep them within the document’s length. See Page Numbers Must Be 1-Indexed and Pages Out of Range.
See Request Options for the full schema.

Error: service_tier Is Only Valid on Parse Jobs

This error occurs when a request to the synchronous Parse endpoint (POST /v2/parse) includes the service_tier parameter. Service tiers only apply to asynchronous endpoints, like Parse Jobs. The parameter is rejected even when its value is empty. Error message:

service_tier (or its deprecated alias priority) is only valid on the async POST /v2/parse/jobs route; sync runs in the fast lane already

What to do:

Remove the service_tier parameter from Parse requests. Parse always runs on the priority tier. See Sync vs Async Processing.
To choose a service tier, create a Parse Job instead. See Choose a Service Tier.

Status 429: Too Many Requests

A 429 means a rate limit rejected the request. The error message states which of two cases you hit and what to do.

The Limit Is Temporarily Exhausted

Recent traffic used up your tier’s limit. Wait and retry with exponential backoff. Error message:

Rate limit exceeded: the limit of {limit} pages per {window} is temporarily exhausted. Please retry shortly.

The Document Is Too Large for the Tier

The document has more pages than the tier admits per request, so retrying never succeeds. Follow the message: submit the document as a standard tier Parse Job, or split it into smaller documents. See Run Large Documents as Async Jobs on the Standard Tier. Error message:

{N} pages exceeds the priority tier ({limit}/request). Larger documents use the standard tier on /v2/parse/jobs, up to {max}/request.

{N} pages exceeds the maximum of {max}/request. Split it into smaller documents.

Status 500: Internal Server Error

This status code indicates that every page in the document failed to process. The response body is still a full parse response: each page in structure.children carries a status of "failed" and a reason, and metadata.failed_pages lists every page. What to do:

Retry the request.
Review the reason on the failed pages for details.
Check whether the document has unusual formatting or corrupted content.
If the error persists, contact support@landing.ai.

Status 504: Gateway Timeout

This error occurs when a synchronous parse request exceeds the timeout limit (475 seconds). The work is cancelled, so retrying starts the parse from the beginning. You are not billed for a request that times out. Error message:

parse did not complete within 475s; use POST /v2/parse/jobs for long-running work

What to do:

Reduce the number of pages per request with the pages option, or split the document into smaller files. See Request Options.
Use Parse Jobs instead. Jobs are not subject to the synchronous timeout and accept larger documents. See Sync vs Async Processing.
If the error persists, contact support@landing.ai.

When Are Credits Consumed?

Credits are consumed only when the Parse API returns a 200 or 206 status code. All other responses, including errors, do not consume credits.

Parse Jobs

This section covers error and status behavior specific to Parse Jobs, the asynchronous Parse API. Errors surface in two places: as HTTP status codes when you create or poll a job, and as a terminal failed job status when parsing itself fails.

Job Creation Errors

Creating a job with POST /v2/parse/jobs returns these status codes:

Status	Meaning
`202 Accepted`	The job was created. The response contains the `job_id`.
`422 Unprocessable Entity`	The request is invalid: an unrecognized `model` version, an encrypted PDF, malformed `options`, an invalid `service_tier` value, a PDF over the page limit, or a document over the size limits. See Rate Limits.
`429 Too Many Requests`	You exceeded your rate limit.
`500 Internal Server Error`	The job could not be queued. Retry the request.

Polling Errors

Polling a job with GET /v2/parse/jobs/{job_id} returns these status codes:

Status	Meaning
`200 OK`	The job status was retrieved. Check the `status` field.
`206 Partial Content`	The job completed, but some pages failed to parse. The result still contains every page; failed pages carry a `status` of `"failed"`.
`404 Not Found`	No job with that `job_id` exists for your account.
`410 Gone`	The job completed, but its result is no longer stored. The error code is `result_expired`. For when results are deleted, see Result Retention. Submit a new job to parse the document again.
`503 Service Unavailable`	The stored result could not be retrieved. The error code is `result_store_unavailable`. This is a transient condition. The result has not expired, so retry with exponential backoff instead of re-running the job.

Failed Jobs

When parsing fails after a job starts, the poll request still returns 200. The failure is reported in the job itself: status is failed and the error field carries a code and a message describing the cause. Jobs have a maximum run time of 6 hours; a job that exceeds it fails. Review the error and resubmit the job to retry.

​Error Response Format

​Common Status Codes

​Parse Status Codes

​Status 206: Partial Content

​Status 422: Unprocessable Entity

​Error: Unknown Model Version

​Error: Invalid document_url Scheme

​Error: document_url Missing Hostname

​Error: document_url Did Not Resolve

​Error: document_url Resolves to a Non-Public IP

​Error: document_url Returned a Redirect

​Error: document_url Fetch Failed

​Error: output_save_url Expired or Expires Too Soon

​Error: Document Exceeds the Size Cap

​Error: Image Exceeds the Maximum Resolution

​Error: Must Provide a Document

​Error: Cannot Provide Both document and document_url

​Error: Page Numbers Must Be 1-Indexed

​Error: Pages Out of Range

​Error: Empty File

​Error: Unsupported or Unrecognized File Format

​Error: Too Many Pages

​Error: Failed to Fetch document_url

​Error: Invalid options Value

​Error: service_tier Is Only Valid on Parse Jobs

​Status 429: Too Many Requests

​The Limit Is Temporarily Exhausted

​The Document Is Too Large for the Tier

​Status 500: Internal Server Error

​Status 504: Gateway Timeout

​When Are Credits Consumed?

​Parse Jobs

​Job Creation Errors

​Polling Errors

​Failed Jobs

Error Response Format

Common Status Codes

Parse Status Codes

Status 206: Partial Content

Status 422: Unprocessable Entity

Error: Unknown Model Version

Error: Invalid document_url Scheme

Error: document_url Missing Hostname

Error: document_url Did Not Resolve

Error: document_url Resolves to a Non-Public IP

Error: document_url Returned a Redirect

Error: document_url Fetch Failed

Error: output_save_url Expired or Expires Too Soon

Error: Document Exceeds the Size Cap

Error: Image Exceeds the Maximum Resolution

Error: Must Provide a Document

Error: Cannot Provide Both document and document_url

Error: Page Numbers Must Be 1-Indexed

Error: Pages Out of Range

Error: Empty File

Error: Unsupported or Unrecognized File Format

Error: Too Many Pages

Error: Failed to Fetch document_url

Error: Invalid options Value

Error: service_tier Is Only Valid on Parse Jobs

Status 429: Too Many Requests

The Limit Is Temporarily Exhausted

The Document Is Too Large for the Tier

Status 500: Internal Server Error

Status 504: Gateway Timeout

When Are Credits Consumed?

Parse Jobs

Job Creation Errors

Polling Errors

Failed Jobs