> ## 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 export const splitJSON = 'split rules'; export const split = 'ADE Split'; export const adeTypeScriptLibrary = 'ade-typescript'; export const adePythonLibrary = 'ade-python'; export const dpt2mini = 'DPT-2 mini'; 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. ### 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, such as {dpt2mini}. **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). **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](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.