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

> Node.js/TypeScript 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/sdk";

try {
  const markdown = await client.convertFile(buffer, { filename: "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 `AbortError`.               |
|       `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/sdk";

try {
  const markdown = await client.convertFile(buffer, { filename: "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/sdk";

try {
  const markdown = await client.convertFile(buffer, { filename: "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>