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 [email protected]. 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 [email protected].

​
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: 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:
  • Provide a document file using the document parameter, OR
  • 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, OR
  • 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.
  • If the PDF is password-protected, remove the password before uploading.
  • Try opening the PDF in a PDF reader to verify it’s not corrupted.
  • If the issue persists, try re-saving or re-exporting the PDF.

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

​
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.
  • Try processing individual pages if the document is very large.
  • If the error persists, contact [email protected].

​
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 [email protected].

​
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.
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 [email protected].

​
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 1MB, they appear in the data field as a ParseResponse object.
  • If results are 1MB 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 [email protected].

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