> This page is for version v2025-04-21. > For other versions, use one of these documentation indexes: > - v2026-02-09 (default): https://docs.extend.ai/2026-02-09/llms.txt > - v2025-04-21: https://docs.extend.ai/2025-04-21/llms.txt > - v2024-12-23: https://docs.extend.ai/2024-12-23/llms.txt > ## Documentation Index > Fetch the complete documentation index at: https://docs.extend.ai/llms.txt > Use this file to discover all available pages before exploring further. > > ## API version > The current API version is `2026-02-09`, served at the site root (no version prefix in URLs). > If this page URL contains `/2025-04-21/` or `/2024-12-23/`, you are reading an older API version. > Prefer the current docs at https://docs.extend.ai/llms.txt unless the user explicitly needs that older version. > Do not treat older-version pages as the source of truth for new integrations. # Error Codes > Handle Parse API errors with detailed error codes and troubleshooting guidance. When an error occurs, the Parse API returns a structured error response with the following fields: | Field | Type | Description | | ----------- | ------- | --------------------------------------------------------------- | | `code` | string | A specific error code that identifies the type of error | | `message` | string | A human-readable description of the error | | `retryable` | boolean | Indicates whether retrying the request might succeed | | `requestId` | string | A 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 Code | Description | Retryable | | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | | `INVALID_CONFIG_OPTIONS` | Invalid combination of options in the incoming config. | ❌ | | `UNABLE_TO_DOWNLOAD_FILE` | The system could not download the file from the provided URL, likely means your presigned url is expired, or malformed somehow. | ❌ | | `FILE_TYPE_NOT_SUPPORTED` | The file type is not supported for parsing. | ❌ | | `FILE_SIZE_TOO_LARGE` | The file exceeds the maximum allowed size. | ❌ | | `CORRUPT_FILE` | The file is corrupt and cannot be parsed. | ❌ | | `OCR_ERROR` | An 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_FILE` | The file is password protected and cannot be parsed. | ❌ | | `FAILED_TO_CONVERT_TO_PDF` | The system could not convert the file to PDF format. | ❌ | | `FAILED_TO_GENERATE_TARGET_FORMAT` | The system could not generate the requested target format. | ❌ | | `INTERNAL_ERROR` | An 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`) * `fileUrl` is not provided in the file object * The provided `fileUrl` 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: **`Error Handling in Node.js`** ```javascript Error Handling in Node.js const parseDocument = async () => { const response = await fetch("https://api.extend.ai/parse", { method: "POST", headers: { "x-extend-api-version": "2025-04-21", "Authorization": "Bearer ", "Content-Type": "application/json", }, body: JSON.stringify({ file: { fileName: "example.pdf", fileUrl: "https://example.com/documents/example.pdf", }, config: { target: "markdown", }, }), }); const data = await response.json(); if (!response.ok) { const { code, message, requestId, retryable } = data; // Handle specific error codes switch (code) { case "FILE_TYPE_NOT_SUPPORTED": console.error("Unsupported file type. Please use a supported format."); break; case "PASSWORD_PROTECTED_FILE": console.error("The file is password protected. Please provide an unprotected file."); break; case "CORRUPT_FILE": console.error("The file is corrupt and cannot be processed."); break; case "FILE_SIZE_TOO_LARGE": console.error("The file is too large. Please reduce the file size."); break; default: console.error(`Error (${code}): ${message}`); } // Log request ID for troubleshooting console.error(`Request ID: ${requestId}`); // Potentially retry if the error is retryable if (retryable) { console.log("This error is retryable. Consider retrying the request."); } throw new Error(`API error: ${code}`); } console.log("Document parsed successfully:", data); return data; }; ``` **`Error Handling in Python`** ```python Error Handling in Python import requests def parse_document(file_url, file_name, config=None): if config is None: config = {"target": "markdown"} url = "https://api.extend.ai/parse" headers = { "x-extend-api-version": "2025-04-21", "Authorization": "Bearer ", "Content-Type": "application/json" } payload = { "file": { "fileName": file_name, "fileUrl": file_url }, "config": config } try: response = requests.post(url, json=payload, headers=headers) response.raise_for_status() # Raise exception for 4XX/5XX responses return response.json() except requests.exceptions.HTTPError as e: error_data = e.response.json() code = error_data.get("code") message = error_data.get("message") request_id = error_data.get("requestId") retryable = error_data.get("retryable", False) # Handle specific error codes if code == "FILE_TYPE_NOT_SUPPORTED": print(f"Error: Unsupported file type. {message}") elif code == "PASSWORD_PROTECTED_FILE": print(f"Error: Password protected file. {message}") elif code == "CORRUPT_FILE": print(f"Error: Corrupt file. {message}") elif code == "FILE_SIZE_TOO_LARGE": print(f"Error: File too large. {message}") else: print(f"Error ({code}): {message}") # Log request ID for troubleshooting print(f"Request ID: {request_id}") # Potentially retry if the error is retryable if retryable: print("This error is retryable. Consider retrying the request.") raise except requests.exceptions.RequestException as e: print(f"Network error: {str(e)}") raise ```