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

> Bun SDK errores tipográficos y estrategia de reintento.

# Manejo de errores

SDK traduce cada código de error HTTP en una subclase de `MarkpdfError` (que extiende `Error`).

```ts theme={null}
import { MarkpdfError } from "@markpdf/bun";

try {
  const markdown = await client.convertFile("./report.pdf");
} catch (err) {
  if (err instanceof MarkpdfError) {
    console.error(`Conversion failed (${err.statusCode}): ${err.detail}`);
  } else {
    throw err;
  }
}
```

## Tabla de errores

| Estado HTTP | Clase                          | causa                                                                              |
| ----------: | ------------------------------ | ---------------------------------------------------------------------------------- |
|     — (red) | `MarkpdfConnectionError`       | No se pudo conectar, se agotó el tiempo de espera o se produjo un error de socket. |
|       `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`        | Sólo con `autoPoll: false`; No es un fallo, indica que hay un trabajo en curso.    |

Todos los exponentes:

```ts theme={null}
class MarkpdfError extends Error {
  statusCode: number | null;
  detail: string;
  requestId: string | null;
}
```

## Capturar errores específicos

```ts theme={null}
import {
  MarkpdfAuthError,
  MarkpdfRateLimitError,
  MarkpdfPayloadTooLargeError,
  MarkpdfVavalidationError,
  MarkpdfServerError,
} from "@markpdf/bun";

try {
  const markdown = await client.convertFile("./report.pdf", { mode: "fast" });
} catch (err) {
  if (err instanceof MarkpdfAuthError) {
    throw new Error("API key invávalida");
  } else if (err instanceof MarkpdfPayloadTooLargeError) {
    console.log("Document too large; try pages= to split it.");
  } else if (err instanceof MarkpdfRateLimitError) {
    console.log(`Rate limited: ${err.detail}`);
  } else if (err instanceof MarkpdfVavalidationError) {
    console.log(`Parámetros invávavalids: ${err.detail}`);
  } else if (err instanceof MarkpdfServerError) {
    console.log("Conversion error; try mode: 'balanced'.");
  } else {
    throw err;
  }
}
```

## Reintentos automáticos

```ts theme={null}
const client = new MarkpdfClient({ apiKey: "YOUR_API_KEY", maxRetries: 4 });
```

* `429` y `5xx`: reintentos con retroceso exponencial y jitter. Respete `Retry-After` si el servidor lo envía.
* `4xx` diferente de `429`: **no** reintentado.
* Errores de red/tiempo de espera: reintento igual que `5xx`.

Deshabilitar SDK reintentos:

```ts theme={null}
const client = new MarkpdfClient({ apiKey: "YOUR_API_KEY", maxRetries: 0 });
```

<Tip />

## Trabajo falvaválido

```ts theme={null}
import { MarkpdfJobFailedError } from "@markpdf/bun";

try {
  const markdown = await client.convertFile("./informe-grande.pdf");
} catch (err) {
  if (err instanceof MarkpdfJobFailedError) {
    console.log(`Job ${err.jobId} falló: ${err.detail}`);
  } else {
    throw err;
  }
}
```

<Warning>
  `MarkpdfJobFailedError` significa que el trabajo ya agotó los reintentos del servidor interno. Volver a intentarlo desde el cliente es razonable, pero hágalo con retroceso.
</Warning>