Core Document ProcessingParsing

Error Codes

When an error occurs, the Parse API returns a structured error response with the following fields:

FieldTypeDescription
codestringA specific error code that identifies the type of error
messagestringA human-readable description of the error
retryablebooleanIndicates whether retrying the request might succeed
requestIdstringA unique identifier for the request, useful for troubleshooting

Custom Error Codes

We provide custom error codes to make it easier for your system to know what happened in case of a failure. There will also be a retryable=true|false field in the response body, but you can also find a breakdown below. Most errors are not retryable and are client errors related to the file provided for parsing.

Error CodeDescriptionRetryable
INVALID_CONFIG_OPTIONSInvalid combination of options in the incoming config.❌
UNABLE_TO_DOWNLOAD_FILEThe system could not download the file from the provided URL, likely means your presigned url is expired, or malformed somehow.❌
FILE_TYPE_NOT_SUPPORTEDThe file type is not supported for parsing.❌
FILE_SIZE_TOO_LARGEThe file exceeds the maximum allowed size.❌
CORRUPT_FILEThe file is corrupt and cannot be parsed.❌
OCR_ERRORAn error occurred in the OCR system. This is a rare error code and would indicate downtime, so requests can be retried. We’d suggest applying a retry with backoff for this error.✅
PASSWORD_PROTECTED_FILEThe file is password protected and cannot be parsed.❌
FAILED_TO_CONVERT_TO_PDFThe system could not convert the file to PDF format.❌
FAILED_TO_GENERATE_TARGET_FORMATThe system could not generate the requested target format.❌
INTERNAL_ERRORAn unexpected internal error occurred. We’d suggest applying a retry with backoff for this error as it likely a result of some outage.✅

HTTP error codes

Corresponding http error codes for different types of failures. We generally recommend relying on our custom error codes for programmatic handling.

400 Bad Request

Returned when:

  • Required fields are missing (e.g., file)
  • url is not provided in the file object
  • The provided url is invalid
  • The config contains invalid values (e.g., unsupported target format or chunking strategy)
  • The file type is not supported
  • The file size is too large

401 Unauthorized

Returned when:

  • The API token is missing
  • The API token is invalid

403 Forbidden

Returned when:

  • The authenticated workspace doesn’t have permission to use the parse functionality
  • The API token doesn’t have sufficient permissions

422 Unprocessable Entity

Returned when:

  • The file is corrupt and cannot be parsed
  • The file is password protected
  • The file could not be converted to PDF
  • The system failed to generate the target format

500 Internal Server Error

Returned when:

  • An OCR error occurs
  • A chunking error occurs
  • Any other unexpected error occurs during parsing

Handling Errors

Here are examples of how to handle errors from the Parse API:

1const parseDocument = async () => {
2  const response = await fetch("https://api.extend.ai/parse", {
3    method: "POST",
4    headers: {
5      "x-extend-api-version": "2026-02-09",
6      "Authorization": "Bearer <API_TOKEN>",
7      "Content-Type": "application/json",
8    },
9    body: JSON.stringify({
10      file: {
11        name: "example.pdf",
12        url: "https://example.com/documents/example.pdf",
13      },
14      config: {
15        target: "markdown",
16      },
17    }),
18  });
19
20  const data = await response.json();
21
22  if (!response.ok) {
23    const { code, message, requestId, retryable } = data;
24
25    // Handle specific error codes
26    switch (code) {
27      case "FILE_TYPE_NOT_SUPPORTED":
28        console.error("Unsupported file type. Please use a supported format.");
29        break;
30      case "PASSWORD_PROTECTED_FILE":
31        console.error("The file is password protected. Please provide an unprotected file.");
32        break;
33      case "CORRUPT_FILE":
34        console.error("The file is corrupt and cannot be processed.");
35        break;
36      case "FILE_SIZE_TOO_LARGE":
37        console.error("The file is too large. Please reduce the file size.");
38        break;
39      default:
40        console.error(`Error (${code}): ${message}`);
41    }
42
43    // Log request ID for troubleshooting
44    console.error(`Request ID: ${requestId}`);
45
46    // Potentially retry if the error is retryable
47    if (retryable) {
48      console.log("This error is retryable. Consider retrying the request.");
49    }
50
51    throw new Error(`API error: ${code}`);
52  }
53
54  console.log("Document parsed successfully:", data);
55  return data;
56};