Manejo de errores

SDK traduce cada código de error HTTP de API en una excepción escrita, todas heredadas de 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}")

Tabla de excepciones

Estado HTTP	Excepción	Causa
— (red)	`MarkpdfConnectionError`	No se pudo conectar o se agotó el tiempo de espera de la red.
`400`	`MarkpdfBadRequestError`	Cuerpo inválido o URL malformado.
`401`	`MarkpdfAuthError`	Falta la clave API o no es válida.
`403`	`MarkpdfForbiddenError`	Clave sin permiso o host no autorizado de URL.
`413`	`MarkpdfPayloadTooLargeError`	Documento, páginas o ZIP fuera de límites.
`415`	`MarkpdfUnsupportedMediaError`	Formato o `content-encoding` no admitido.
`422`	`MarkpdfVavalidationError`	Faltan parámetros requeridos.
`429`	`MarkpdfRateLimitError`	Demasiadas peticiones.
`5xx`	`MarkpdfServerError`	Error de conversión en el servidor.
— (trabajo)	`MarkpdfJobFailedError`	El trabajo en cola (`202`) falló después de reintentos internos.
— (trabajo)	`MarkpdfJobQueuedError`	Solo se inicia con `auto_poll=Failedse`; No es un error, indica que hay un trabajo en progreso.

Todos heredan de markpdf.MarkpdfError, que establece:

int | None

Código HTTP original o None para errores de red.

str

Mensaje detail devuelto por API.

str | None

Si la respuesta trae un encabezado de identificación de solicitud, se expone aquí para informar el problema.

##Capturar excepciones específicas

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'.")

Reintentos automáticos

El cliente reintenta automáticamente 429 y 5xx con un retroceso exponencial de hasta max_retries (predeterminado 2):

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

429 y 5xx: reintentado. Respete el encabezado Retry-After si está presente; de lo contrario, utilice un retroceso exponencial con fluctuación.
4xx distinto de 429: no reintentado: el error casi siempre significa que la solicitud debe corregirse, no repetirse.
Errores de red (MarkpdfConnectionError): reintento igual que 5xx.

Para desactivar SDK reintentos y gestionarlos usted mismo:

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

Trabajo falvaválido

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 significa que el trabajo ya agotó los reintentos del servidor interno. Volver a intentar la misma conversión desde el cliente es razonable, pero hágalo con un retroceso: probablemente todos los backends todavía estén saturados.

Python

Node.js / TypeScript

C++

Next.js

Angular

React

React Native

Svelte

Bun

Flutter

Java

Kotlin

Manejo de errores

Manejo de errores

Tabla de excepciones

Reintentos automáticos

Trabajo falvaválido

​Manejo de errores

​Tabla de excepciones

​Reintentos automáticos

​Trabajo falvaválido

Manejo de errores

Tabla de excepciones

Reintentos automáticos

Trabajo falvaválido