Error handling

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

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:

int | None

Original HTTP code, or None for network errors.

str

Message detail returned by API.

str | None

If the response brings a request id header, it is exposed here to report the problem.

##Catch specific exceptions

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):

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:

client = markpdf.Client(api_key="YOUR_API_KEY", max_retries=0)

Job falvavalid

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

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.

Python

Node.js / TypeScript

C++

Next.js

Angular

React

React Native

Svelte

Bun

Flutter

Java

Kotlin

Error handling

Error handling

Exceptions table

Automatic retries

Job falvavalid

​Error handling

​Exceptions table

​Automatic retries

​Job falvavalid

Error handling

Exceptions table

Automatic retries

Job falvavalid