Error Handling

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

How failures surface: sync vs. async

Where an error shows up depends on which endpoint you use.

• Synchronous (/parse) waits for processing to finish, so every failure — both request validation and document processing — comes back as an HTTP error response with the fields above. The HTTP status codes below apply to this endpoint.
• Asynchronous (/parse_runs) returns 200 with a parse run as soon as the job is accepted. Request-level problems (invalid request, auth) still return an HTTP error at creation time, but document processing failures are not HTTP errors — the run instead reaches status: "FAILED" with a failureReason and failureMessage (one of the custom error codes below), which you read when you poll or receive the webhook.

Custom error codes

We provide custom error codes so your system can tell exactly what happened. On the sync endpoint they appear in the error body’s code field; on the async endpoint they appear as the run’s failureReason. Most are client errors related to the file provided for parsing and are not retryable.

HTTP status codes

These HTTP status codes are returned by the synchronous /parse endpoint. On the asynchronous /parse_runs endpoint, only request-level errors (400, 401, 403) are returned at creation time — processing failures surface on the run as status: "FAILED". We generally recommend relying on the custom error codes above 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

Error handling differs between the two endpoints: with sync you catch a thrown HTTP error, while with async you also check the run’s terminal status. Pick the tab that matches how you call Parse.

1
from extend_ai import Extend
2
from extend_ai.core.api_error import ApiError
3
4
client = Extend(token="your_api_key")
5
6
try:
7
    response = client.parse(file={"url": "https://example.com/document.pdf"})
8
except ApiError as e:
9
    # e.body holds the structured error: { code, message, retryable, requestId }
10
    body = e.body or {}
11
    if body.get("retryable"):
12
        ...  # retry with exponential backoff
13
    print(f"parse failed ({e.status_code}): {body.get('code')} — {body.get('message')}")
14
    raise

For retryable errors (OCR_ERROR, INTERNAL_ERROR, or any 5xx), retry with exponential backoff. Always log the requestId when contacting support.