Skip to main content
Use this section to troubleshoot issues encountered when calling the Parse v2 API.

​
Error Response Format

Every error from the v2 APIs returns a JSON body with two fields:
The code field is a stable snake_case 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.

​
Parse Status Codes

​
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:
What to do:
  • Omit the model field to use the latest version by default.
  • Supply a valid version: the dpt-3-pro-latest alias, or a dated snapshot such as dpt-3-pro-20260710. See Model Version.

​
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:
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:
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:
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:
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:
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:
or
or
What to do:
  • Verify the URL serves the file and is publicly reachable.
  • If the URL is presigned, confirm it has not expired.

​
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:
or
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: Must Provide a Document

This error occurs when your request includes neither the document nor the document_url parameter. Error message:
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:
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. Page numbers beyond the document’s length do not cause an error; they are silently ignored. Error message:
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: Empty File

This error occurs when the uploaded file contains no data. Error message:
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 or image. The format is detected from the file’s content, not its extension or Content-Type header. Error message:
or
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:
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:
or
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:
or
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. See Page Numbers Must Be 1-Indexed.
  • 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:
What to do:

​
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:

​
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:
or

​
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:
What to do:

​
When Are Credits Consumed?

Credits are consumed only when the Parse v2 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 v2, 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:

​
Polling Errors

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

​
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.