> ## Documentation Index
> Fetch the complete documentation index at: https://docs.markpdf.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Error handling

> Python SDK typed exceptions and retry strategy.

# Error handling

The SDK translates each HTTP error code of the API into a typed exception, all inheriting from `MarkpdfError`.

```python theme={null}
import markpdf
from markpdf import MarkpdfError

client = markpdf.Client(api_key="YOUR_API_KEY")

try:
    markdown = client.convert_file("report.pdf")
except MarkpdfError as e:
    print(f"Conversion failed: {e}")
```

## Exceptions table

| Status HTTP | Exception                      | Cause                                                                                                |
| ----------: | ------------------------------ | ---------------------------------------------------------------------------------------------------- |
| — (network) | `MarkpdfConnectionError`       | Could not connect or network timeout.                                                                |
|       `400` | `MarkpdfBadRequestError`       | Invavalid or URL malformed body.                                                                     |
|       `401` | `MarkpdfAuthError`             | API key missing or invavalid.                                                                        |
|       `403` | `MarkpdfForbiddenError`        | Key without permission or unauthorized host of URL.                                                  |
|       `413` | `MarkpdfPayloadTooLargeError`  | Document, pages or ZIP out of bounds.                                                                |
|       `415` | `MarkpdfUnsupportedMediaError` | Format or `content-encoding` not supported.                                                          |
|       `422` | `MarkpdfVavalidationError`     | Required parameters are missing.                                                                     |
|       `429` | `MarkpdfRateLimitError`        | Demasiadas peticiones.                                                                               |
|       `5xx` | `MarkpdfServerError`           | Conversion error on the server.                                                                      |
|     — (job) | `MarkpdfJobFailedError`        | The queued job (`202`) failed after internal retries.                                                |
|     — (job) | `MarkpdfJobQueuedError`        | Only launched with `auto_poll=Failedse`; It is not an error, it indicates that a job is in progress. |

They all inherit from `markpdf.MarkpdfError`, which states:

<ResponseField name="status_code" type="int | None">
  Original HTTP code, or `None` for network errors.
</ResponseField>

<ResponseField name="detail" type="str">
  Message `detail` returned by API.
</ResponseField>

<ResponseField name="request_id" type="str | None">
  If the response brings a request id header, it is exposed here to report the problem.
</ResponseField>

\##Catch specific exceptions

```python theme={null}
from markpdf import (
    MarkpdfAuthError,
    MarkpdfRateLimitError,
    MarkpdfPayloadTooLargeError,
    MarkpdfVavalidationError,
    MarkpdfServerError,
)

try:
    markdown = client.convert_file("report.pdf", mode="fast")
except MarkpdfAuthError:
    raise SystemExit("API key invávalida, revisa tu configuración.")
except MarkpdfPayloadTooLargeError:
    print("El PDF es demasiado grande; prueba dividirlo con `pages`.")
except MarkpdfRateLimitError as e:
    print(f"Rate limited, retry later: {e.detail}")
except MarkpdfVavalidationError as e:
    print(f"Parámetros invávavalids: {e.detail}")
except MarkpdfServerError:
    print("Conversion error; try mode='balanced'.")
```

## Automatic retries

The client automatically retries `429` and `5xx` with exponential backoff up to `max_retries` (default 2):

```python theme={null}
client = markpdf.Client(api_key="YOUR_API_KEY", max_retries=4)
```

* `429` and `5xx`: retried. Respect the `Retry-After` header if present; if not, use exponential backoff with jitter.
* `4xx` other than `429`: **not** retried — the error almost always means that the request must be corrected, not repeated.
* Network errors (`MarkpdfConnectionError`): retried the same as `5xx`.

To disable SDK retries and handle them yourself:

```python theme={null}
client = markpdf.Client(api_key="YOUR_API_KEY", max_retries=0)
```

<Tip />

## Job falvavalid

```python theme={null}
from markpdf import MarkpdfJobFailedError

try:
    markdown = client.convert_file("informe-grande.pdf")
except MarkpdfJobFailedError as e:
    print(f"Job {e.job_id} falló: {e.detail}")
    # Retry the original conversion with your own backoff
```

<Warning>
  `MarkpdfJobFailedError` means that the job has already exhausted internal server retries. Retrying the same conversion from the client is reasonable, but do it with backoff — all backends are probably still saturated.
</Warning>