Skip to main content
Use this section to troubleshoot issues encountered when calling the parse APIs:

​
Common Status Codes

These status codes apply to all parse endpoints.

​
ADE Parse

This section covers errors for the ADE Parse API.

​
Status Codes

​
Status 206: Partial Content

Applies to: ADE Parse and ADE Get Parse Jobs This response occurs when the document was parsed successfully but some pages failed during processing. The response includes:
  • A 206 status code
  • Parsed content for successful pages
  • A failed_pages array in the metadata listing which pages failed (zero-indexed)
  • For ADE Get Parse Jobs only: A failure_reason field with details about the failures
Because the API returns at least partial results, the API call consumes credits. What to do:
  • Review the failed_pages field in the metadata to identify which pages failed.
  • For ADE Get Parse Jobs, also review the failure_reason field for details about the failures.
  • Check if the failed pages are corrupted or have unusual formatting.
  • If the issue persists with specific pages, contact support@landing.ai.

​
Status 400: Bad Request

This status code indicates invalid request parameters or client-side errors. Review the specific error message to identify the issue.

​
Error: Failed to download document from URL

This error occurs when the API cannot download the document from the provided document_url. Error message:
What to do:
  • Verify the URL is accessible and returns valid content.
  • Check network connectivity and URL permissions.
  • Ensure the URL points to a supported document type.

​
Error: Invalid Document Format

converts text documents and presentations to PDFs before parsing them. This error occurs when a text document or presentation cannot be converted to PDF. The file may be password-protected or corrupted. Error message:
What to do:
  • Verify the document is not corrupted by opening it in the appropriate application (such as Microsoft Word or Microsoft PowerPoint).
  • Open the document in the appropriate application (such as Microsoft Word or Microsoft PowerPoint) and resave it.

​
Error: Unsupported model

This error occurs when an invalid or unsupported model version is specified. Error message:
What to do:
  • Check the API documentation for supported model versions.
  • If you don’t specify a version, the API uses the latest version by default.
  • Verify the model version string is formatted correctly.

​
Error: Deprecated model version

This error occurs when the model parameter specifies a deprecated model version. The family (dpt-1, dpt-1-latest, and dated snapshots) and dpt-2-mini are deprecated. Error message:
What to do: Update the model parameter to a supported version, such as dpt-2. See Parsing Models.

​
Status 422: Unprocessable Entity

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

​
Error: Cannot provide both ‘document’ and ‘document_url’

This error occurs when both a document file and a URL to a document are provided in the same request. Error message:
What to do: Choose one input method and remove the other from your request:
  • Provide a document file using the document parameter.
  • Provide a URL to a document using the document_url parameter.

​
Error: Must provide either ‘document’ or ‘document_url’

This error occurs when your request does not include either the document or document_url parameter. Error message:
What to do: Add one of these parameters to your request:
  • Use the document parameter to upload a document file.
  • Use the document_url parameter to provide a URL to a document.

​
Error: Invalid URL format

This error occurs when the document_url parameter contains an invalid URL. Error message:
What to do:
  • Verify the URL is properly formatted with a valid protocol (http:// or https://).
  • Check for typos or missing characters in the URL.
  • Ensure the URL is properly encoded if it contains special characters.

​
Error: PDF must not exceed X pages

This error occurs when the PDF page count exceeds your account’s page limit. Error message:
What to do:
  • Reduce the PDF page count. To see the maximum number of pages allowed, go to Rate Limits.
  • Consider using the ADE Parse Jobs API, which allows you to process longer documents.

​
Error: PDF contains zero pages

This error occurs when the PDF file has no pages. Error message:
What to do: Use a valid PDF file that contains at least one page of content.

​
Error: Failed to open or read PDF

This error occurs when the PDF file is corrupted or cannot be opened. Error message:
or
What to do:
  • Use a valid, non-corrupted PDF file.
  • Open the PDF in a PDF reader to verify it’s not corrupted.
  • Re-save or re-export the PDF.

​
Error: Document Is Password-Protected

This error occurs when you submit a password-protected file without providing the password parameter. Error message:
What to do:
  • If you have ZDR enabled: Add the password parameter to your request. For more information, go to Parse Password-Protected Files.
  • If you don’t have ZDR enabled: Parsing password-protected files is not supported for your account. Remove the password and try again.

​
Error: Failed to Decrypt Document

This error occurs if you have Zero Data Retention (ZDR) enabled, included the password parameter (see Parse Password-Protected Files), and the password is incorrect or the file is corrupted. Error message:
What to do:
  • Verify the password is correct.
  • Open the file in the appropriate application to confirm it is not corrupted.

​
Error: Password-Protected Documents Not Supported for Your Account

This error occurs when the password parameter is included in the request but Zero Data Retention (ZDR) is not enabled on your account. Error message:
What to do:
  • Remove the password from the document before uploading and try again.
  • To parse password-protected files, enable ZDR on your account. For more information, go to Zero Data Retention.

​
Error: Multiple document files detected

This error occurs when multiple document files are included in the request. Error message:
What to do: Send only one document file per request.

​
Error: File is empty

This error occurs when the uploaded file contains no data. Error message:
What to do: Ensure you are uploading a valid file with content (not an empty file).

​
Error: Failed to Convert Document to Supported Format

converts text documents and presentations to PDFs before parsing them. This error occurs when a document is converted to PDF successfully but the resulting PDF is empty or contains no extractable content. Error message:
What to do:
  • Verify the document contains actual content, not just blank pages or empty slides.
  • Check that the document doesn’t consist only of unsupported elements (such as embedded objects that cannot be converted).
  • Open the document in the appropriate application (such as Microsoft Word or Microsoft PowerPoint) and resave it.

​
Error: Unsupported Format

This error occurs when the uploaded file format is not supported. Error message:
What to do:
  • Check the list of supported file types.
  • Convert your document to a supported format before uploading.
  • Verify the file extension matches the actual file content.

​
Error: Unsupported Spreadsheet Format

This error occurs when the uploaded spreadsheet file format is not supported. Error message:
What to do:
  • Convert your spreadsheet to .xlsx or .csv format.
  • Verify the file extension matches the actual file content.

​
Error: Spreadsheet File Too Large

This error occurs when the uploaded spreadsheet exceeds the 50 MB size limit. Error message:
What to do:
  • Split your spreadsheet into multiple smaller files.
  • Remove unnecessary data or sheets to reduce file size.

​
Error: Invalid custom_prompts Value

Applies to: ADE Parse and ADE Parse Jobs This error occurs when the custom_prompts parameter fails validation. Common causes include:
  • The figure prompt exceeds 512 characters
  • An unsupported key is used (only figure is supported)
  • The value for the figure key is not a string
  • The value is not a JSON object
  • The value is not valid JSON
Error messages:
What to do:
  • Ensure custom_prompts is a valid JSON string in object format: {"figure": "your prompt"}.
  • Use only the figure key. Any other key will be rejected.
  • Keep the figure prompt to 512 characters or fewer.
  • For more information, see Custom Prompts for Figure Descriptions.

​
Error: custom_prompts Not Supported for Model

Applies to: ADE Parse and ADE Parse Jobs This error occurs when the custom_prompts parameter is used with a model that does not support it. Error message:
What to do:

​
Status 500: Internal Server Error

This error indicates all pages in the document failed to process. Error message:
What to do:
  • Retry the request.
  • Check if the document has unusual formatting or corrupted content.
  • If the document is very large, process individual pages.
  • If the error persists, contact support@landing.ai.

​
Status 504: Gateway Timeout

This error occurs when the parsing process 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:
  • Reduce the document size or number of pages.
  • Split large documents into smaller files.
  • Use the ADE Parse Jobs API instead. Jobs are not subject to the synchronous timeout.
  • If the error persists, contact support@landing.ai.

​
ADE Parse Jobs

This section covers errors for the ADE Parse Jobs API, which creates asynchronous parse jobs.

​
Status Codes

​
Status 400: Bad Request

​
Error: output_save_url must be present if zeroDataRetention is enabled

This error occurs when Zero Data Retention (ZDR) is enabled but no output save URL is provided. Error message:
What to do: When using Zero Data Retention (ZDR), you must provide an output_save_url where the parsed results will be saved. The results will not be returned in the API response when ZDR is enabled.

​
Error: Only document_url is accepted if zeroDataRetention is enabled

This error occurs when Zero Data Retention (ZDR) is enabled but a document file is uploaded instead of providing a URL. Error message:
What to do: When using Zero Data Retention (ZDR), you must use the document_url parameter to provide a URL to your document. Direct file uploads via the document parameter are not supported with ZDR.

​
Status 500: Internal Server Error

This error indicates a server-side failure during job creation or enqueuing. Error message:
or
or
or
What to do:

​
ADE Get Parse Jobs

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

​
Status Codes

​
Job Status Values

The status field in the response indicates the current state of the job:

​
Understanding the Response

For completed jobs:
  • If results are less than 1 MB, they appear in the data field as a ParseResponse object.
  • If results are 1 MB or larger, the output_url field contains a presigned S3 URL (expires after 1 hour).
  • If Zero Data Retention is enabled, results are always saved to your output_save_url and not included in the response.
For failed jobs:
  • Check the failure_reason field for error details.
  • Common failure reasons include document processing errors or timeout.
Progress tracking:
  • The progress field shows completion as a decimal from 0 to 1 (e.g., 0.5 = 50% complete).
  • Progress is based on the number of pages processed.

​
Partial Content in Completed Jobs

A job can have status completed even if some pages failed to process. When this occurs, the API returns a 206 status code. For details on handling partial content, see Status 206: Partial Content.

​
ADE List Parse Jobs

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

​
Status Codes

​
Query Parameters

You can filter and paginate the job list using these parameters:
  • page: Page number for pagination (default: 1)
  • page_size: Number of jobs per page (default: 10)
  • status: Filter by job status (pending, processing, completed, failed, cancelled)

​
Understanding the Response

The response contains:
  • jobs: Array of job summaries with job_id, status, received_at timestamp, and progress.
  • has_more: Boolean indicating if more pages are available.
  • For failed jobs, the failure_reason field provides error details.

​
When Are Credits Consumed?

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