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.
Status CodeNameDescriptionWhat to Do
401UnauthorizedMissing or invalid API key.Check that your apikey header is present and contains a valid API key.
402Payment RequiredYour 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.
429Too Many RequestsRate limit exceeded.Wait before retrying. Reduce request frequency and implement exponential backoff.

​
ADE Parse

This section covers errors for the ADE Parse API.

​
Status Codes

Status CodeNameDescriptionWhat to Do
200SuccessDocument parsed successfully and returned immediately.Continue with normal operations.
206Partial ContentDocument parsed but some pages failed during processing.Review the failed_pages field in the metadata. See Status 206.
400Bad RequestInvalid request due to document download failure or unsupported model version.Review error message for specific issue. See Status 400.
422Unprocessable EntityInput validation failed.Review your request parameters. See Status 422.
500Internal Server ErrorAll pages failed to process.Retry. If the issue persists, contact support@landing.ai. See Status 500.
504Gateway TimeoutRequest processing exceeded the timeout limit (475 seconds).Reduce document size or number of pages. See Status 504.

​
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: 
Failed to download document from URL: {error_details}
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: 
Invalid document format. The file may be corrupted or password-protected.
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: 
Unsupported model: {version}
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.

​
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: 
Cannot provide both 'document' and 'document_url'. Please provide only one.
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: 
Must provide either 'document' or 'document_url'.
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: 
Invalid URL format: {url}
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: 
PDF must not exceed {limit} pages.
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: 
PDF contains zero pages. Please provide a PDF with at least one page.
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: 
Failed to read PDF document: {error_details}
or 
Failed to open PDF. Ensure it is a valid PDF file.
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: 
Document is password-protected. Please provide the password parameter.
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: 
Failed to decrypt {document_type} document. The password is incorrect or the file is corrupted.
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: 
Password-protected documents are not currently supported for your account. Please remove the password from your document before uploading.
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: 
Multiple document files detected (X). Please provide only one document file.
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: 
File is empty.
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: 
Failed to convert document to supported format
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: 
Unsupported format: {mime_type} ({filename}). Supported formats: {supported_formats}
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: 
Unsupported format: {filename}. Supported formats: .xlsx, .csv
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: 
Spreadsheet file too large (max 50 MB). Please split into smaller files.
What to do:
  • Split your spreadsheet into multiple smaller files.
  • Remove unnecessary data or sheets to reduce file size.

​
Status 500: Internal Server Error

This error indicates all pages in the document failed to process. Error message: 
Failed to process the document
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). Error message: 
Request timed out after {seconds} seconds
What to do:
  • Reduce the document size or number of pages.
  • Split large documents into smaller files.
  • 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 CodeNameDescriptionWhat to Do
202AcceptedJob created successfully and queued for processing.Use the returned job_id to check job status with the ADE Get Parse Jobs API.
400Bad RequestInvalid request parameters.Review the error message for details. See Status 400.
422Unprocessable EntityInput validation failed.Review your request parameters. Common errors include missing required fields, ZDR configuration issues, or invalid input. See errors below.
429Too Many RequestsRate limit exceeded.Wait before retrying. Reduce request frequency and implement exponential backoff.

​
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: 
output_save_url must be present if zeroDataRetention is enabled
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: 
Only document_url is accepted if zeroDataRetention is enabled
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: 
Failed to enqueue job for processing
or 
Internal server error during document parsing
or 
Failed to create async job
or 
Failed to upload document to S3
What to do:

​
ADE Get Parse Jobs

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

​
Status Codes

Status CodeNameDescriptionWhat to Do
200SuccessJob status retrieved successfully.Check the status field. If completed, results are in the data field (for small results) or output_url field (for large results or ZDR).
206Partial ContentJob completed but some pages failed during processing.Review the failed_pages field in the metadata and the failure_reason field. See Status 206.
404Not FoundJob with the specified ID not found.Verify the job ID is correct. The job may belong to a different API key.
422Unprocessable EntityInput validation failed.Verify the job ID format is correct.
500Internal Server ErrorServer error during job status retrieval.Retry. If the issue persists, contact support@landing.ai.

​
Job Status Values

The status field in the response indicates the current state of the job:
StatusDescription
pendingJob is queued and waiting to be processed.
processingJob is currently being processed.
completedJob completed successfully. Results are available in the response.
failedJob failed during processing. Check the failure_reason field for details.
cancelledJob was cancelled.

​
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

Status CodeNameDescriptionWhat to Do
200SuccessJob list retrieved successfully.Review the list of jobs and their statuses.
500Internal Server ErrorServer error during job listing.Retry. If the issue persists, contact support@landing.ai.

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