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

# Error handling

> Node.js/TypeScript SDK typos and retry strategy.

# Error handling

The SDK translates each HTTP error code into a subclass of `MarkpdfError` (which extends `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;
  }
}
```

## Error table

| Status HTTP | Clase                          | Causa                                                                                     |
| ----------: | ------------------------------ | ----------------------------------------------------------------------------------------- |
| — (network) | `MarkpdfConnectionError`       | Could not connect, timeout or `AbortError`.                                               |
|       `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 with `autoPoll: false`; It is not a failure, it indicates that a job is in progress. |

Todas exponen:

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

## Capture specific errors

```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;
  }
}
```

## Automatic retries

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

* `429` and `5xx`: retries with exponential backoff and jitter. Honor `Retry-After` if the server sends it.
* `4xx` different from `429`: **not** retried.
* Network/timeout errors: retried same as `5xx`.

Disable SDK retries:

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

<Tip />

## Job falvavalid

```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` means that the job has already exhausted internal server retries. Retrying from the client is reasonable, but do it with backoff.
</Warning>