Error Handling

When an error occurs, the Edit 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 (/edit) 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 (/edit_runs) returns 200 with an edit 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 failure reasons below), which you read when you poll or receive the webhook.

Failure reasons

These codes describe why an edit failed. 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 or config and are not retryable. The structured error’s retryable flag is authoritative at runtime.

HTTP status codes

These HTTP status codes are returned by the synchronous /edit endpoint. On the asynchronous /edit_runs endpoint, only request-level errors are returned at creation time — processing failures surface on the run as status: "FAILED". We generally recommend relying on the failure reasons above for programmatic handling.

400 Bad Request

Returned when required fields are missing (e.g. file), the file locator is invalid, or the config contains invalid options.

401 Unauthorized

Returned when the API token is missing or invalid.

402 Payment Required

Returned when the workspace has insufficient credits to process the file.

403 Forbidden

Returned when the authenticated workspace or token doesn’t have permission to use the edit functionality.

404 Not Found

Returned when a referenced file or resource cannot be found.

422 Unprocessable Entity

Returned when the file cannot be processed — for example, it is corrupt, password protected, or could not be converted to PDF.

429 Too Many Requests

Returned when you exceed the rate limit. Retry with exponential backoff.

500 Internal Server Error

Returned when an unexpected error occurs during editing. Retry with exponential backoff.

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

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
    result = client.edit(
8
        file={"url": "https://example.com/form.pdf"},
9
        config={"instructions": "Fill out the form with the provided data."},
10
    )
11
except ApiError as e:
12
    # e.body holds the structured error: { code, message, retryable, requestId }
13
    body = e.body or {}
14
    if body.get("retryable"):
15
        ...  # retry with exponential backoff
16
    print(f"edit failed ({e.status_code}): {body.get('code')} — {body.get('message')}")
17
    raise

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