> ## Documentation Index > Fetch the complete documentation index at: https://docs.landing.ai/llms.txt > Use this file to discover all available pages before exploring further. # Troubleshoot Parsing > Resolve Parse and Parse Jobs errors using status codes, causes, and fixes for failed or partial results. export const splitJSON = 'split rules'; export const split = 'ADE Split'; export const adeTypeScriptLibrary = 'ade-typescript'; export const adePythonLibrary = 'ade-python'; export const dpt2 = 'DPT-2'; export const dpt1 = 'DPT-1'; export const dpt = 'Document Pre-Trained Transformer'; export const companyName = 'LandingAI'; export const extract = 'ADE Extract'; export const parse = 'ADE Parse'; export const ade = 'Agentic Document Extraction'; Use this section to troubleshoot issues encountered when calling the parse APIs: * **[{parse}](https://docs.landing.ai/api-reference/tools/ade-parse)**: `/v1/ade/parse` * **[ADE Parse Jobs](https://docs.landing.ai/api-reference/tools/ade-parse-jobs)**: `/v1/ade/parse/jobs` * **[ADE Get Parse Jobs](https://docs.landing.ai/api-reference/tools/ade-get-parse-job)**: `/v1/ade/parse/jobs/{job_id}` * **[ADE List Parse Jobs](https://docs.landing.ai/api-reference/tools/ade-list-parse-jobs)**: `/v1/ade/parse/jobs` ## Common Status Codes These status codes apply to all parse endpoints. | Status Code | Name | Description | What to Do | | ----------- | ----------------- | ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | 401 | Unauthorized | Missing or invalid API key. | Check that your `apikey` header is present and contains a valid [API key](./agentic-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](./agentic-api-key). Add more credits to your account. | | 429 | Too Many Requests | Rate 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 Code | Name | Description | What to Do | | ----------- | --------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- | | 200 | Success | Document parsed successfully and returned immediately. | Continue with normal operations. | | 206 | Partial Content | Document parsed but some pages failed during processing. | Review the `failed_pages` field in the metadata. See [Status 206](#status-206-partial-content). | | 400 | Bad Request | Invalid request due to document download failure or unsupported model version. | Review error message for specific issue. See [Status 400](#status-400-bad-request). | | 422 | Unprocessable Entity | Input validation failed. | Review your request parameters. See [Status 422](#status-422-unprocessable-entity). | | 500 | Internal Server Error | All pages failed to process. | Retry. If the issue persists, contact [support@landing.ai](mailto:support@landing.ai). See [Status 500](#status-500-internal-server-error). | | 504 | Gateway Timeout | Request processing exceeded the timeout limit (475 seconds). | Reduce document size or number of pages. See [Status 504](#status-504-gateway-timeout). | ### 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](mailto: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 {ade} 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. #### Error: Deprecated model version This error occurs when the `model` parameter specifies a deprecated model version. The {dpt1} family (`dpt-1`, `dpt-1-latest`, and dated snapshots) and `dpt-2-mini` are deprecated. **Error message:** ``` The specified model version '{version}' is deprecated. Please use a supported model version. See https://docs.landing.ai/dpt3/parse for the latest models. ``` **What to do:** Update the `model` parameter to a supported version, such as `dpt-2`. See [Parsing Models](./ade-parse-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:** ``` 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](./ade-rate-limits). * Consider using the [ADE Parse Jobs](./ade-parse-async) 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](./ade-parse-password). * **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)](./zdr) enabled, included the `password` parameter (see [Parse Password-Protected Files](./ade-parse-password)), 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)](./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](./zdr). #### 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 {ade} 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](./ade-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. #### 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:** ``` custom_prompts['figure'] must be 512 characters or fewer. ``` ``` Input should be 'figure' ``` **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](./ade-parse-custom-prompts). #### 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:** ``` custom_prompts is not supported for the '{model_name}' model. Please use a different model or remove the custom_prompts parameter. ``` **What to do:** * Use {dpt2} when using `custom_prompts`. For more information, see [Custom Prompts for Figure Descriptions](./ade-parse-custom-prompts). ### 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](mailto: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:** ``` Request timed out after {seconds} seconds ``` **What to do:** * Reduce the document size or number of pages. * Split large documents into smaller files. * Use the [ADE Parse Jobs](./ade-parse-async) API instead. Jobs are not subject to the synchronous timeout. * If the error persists, contact [support@landing.ai](mailto:support@landing.ai). ## ADE Parse Jobs This section covers errors for the ADE Parse Jobs API, which creates asynchronous parse jobs. ### Status Codes | Status Code | Name | Description | What to Do | | ----------- | -------------------- | --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | 202 | Accepted | Job created successfully and queued for processing. | Use the returned `job_id` to check job status with the [ADE Get Parse Jobs](#ade-get-parse-jobs) API. | | 400 | Bad Request | Invalid request parameters. | Review the error message for details. See [Status 400](#status-400-bad-request-2). | | 422 | Unprocessable Entity | Input validation failed. | Review your request parameters. Common errors include missing required fields, ZDR configuration issues, or invalid input. See errors below. | | 429 | Too Many Requests | Rate 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:** * Retry the request. * If the error persists, contact [support@landing.ai](mailto:support@landing.ai). ## ADE Get Parse Jobs Use this section to troubleshoot issues encountered when calling the **[ADE Get Parse Jobs](https://docs.landing.ai/api-reference/tools/ade-get-parse-job)** API. ### Status Codes | Status Code | Name | Description | What to Do | | ----------- | --------------------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | | 200 | Success | Job 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). | | 206 | Partial Content | Job completed but some pages failed during processing. | Review the `failed_pages` field in the metadata and the `failure_reason` field. See [Status 206](#status-206-partial-content). | | 404 | Not Found | Job with the specified ID not found. | Verify the job ID is correct. The job may belong to a different API key. | | 422 | Unprocessable Entity | Input validation failed. | Verify the job ID format is correct. | | 500 | Internal Server Error | Server error during job status retrieval. | Retry. If the issue persists, contact [support@landing.ai](mailto:support@landing.ai). | ### Job Status Values The `status` field in the response indicates the current state of the job: | Status | Description | | ------------ | --------------------------------------------------------------------------- | | `pending` | Job is queued and waiting to be processed. | | `processing` | Job is currently being processed. | | `completed` | Job completed successfully. Results are available in the response. | | `failed` | Job failed during processing. Check the `failure_reason` field for details. | | `cancelled` | Job 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](#status-206-partial-content). ## ADE List Parse Jobs Use this section to troubleshoot issues encountered when calling the **[ADE List Parse Jobs](https://docs.landing.ai/api-reference/tools/ade-list-parse-jobs)** API. ### Status Codes | Status Code | Name | Description | What to Do | | ----------- | --------------------- | -------------------------------- | -------------------------------------------------------------------------------------- | | 200 | Success | Job list retrieved successfully. | Review the list of jobs and their statuses. | | 500 | Internal Server Error | Server error during job listing. | Retry. If the issue persists, contact [support@landing.ai](mailto: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 {parse} or ADE Get Parse Jobs API returns a 200 or 206 status code. All other responses, including errors, do not consume credits.