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

# Manejo de errores

> Python SDK excepciones escritas y estrategia de reintento.

# Manejo de errores

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

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

<ResponseField name="status_code" type="int | None">
  Código HTTP original o `None` para errores de red.
</ResponseField>

<ResponseField name="detail" type="str">
  Mensaje `detail` devuelto por API.
</ResponseField>

<ResponseField name="request_id" type="str | None">
  Si la respuesta trae un encabezado de identificación de solicitud, se expone aquí para informar el problema.
</ResponseField>

\##Capturar excepciones específicas

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

## Reintentos automáticos

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

```python theme={null}
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:

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

<Tip />

## Trabajo falvaválido

```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` 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.
</Warning>