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

> Cómo se propagan los errores API en los controladores de ruta y las acciones del servidor.

# Manejo de errores

`@markpdf/nextjs` reutiliza excepciones de [`@markpdf/sdk`](/docs/public/es/sdks/nodejs/error-handling) (`MarkpdfAuthError`, `MarkpdfRateLimitError`, etc.), todos los hijos de `MarkpdfError`. La forma de manejarlos depende de si se encuentra en un controlador de ruta o en una acción del servidor.

## En un controlador de ruta

`createConvertRouteHandler` ya traduce cualquier `MarkpdfError` en una respuesta HTTP con el mismo código de estado y un cuerpo `{ error: string }`:

```json theme={null}
// 413 Payload Too Large
{ "error": "Document too large. Reduce the size or split the document." }
```

Si crea su propio controlador de ruta con `getServerClient`, captúrelo usted mismo:

```ts app/api/convert/route.ts theme={null}
import { getServerClient } from "@markpdf/nextjs";
import { MarkpdfError, MarkpdfAuthError, MarkpdfRateLimitError } from "@markpdf/sdk";
import { NextResponse } from "next/server";

export async function POST(req: Request) {
  const client = getServerClient({ apiKey: process.env.MARKPDF_API_KEY! });
  const form = await req.formData();
  const file = form.get("file") as File;

  try {
    const markdown = await client.convertFile(file, { filename: file.name, mode: "fast" });
    return new NextResponse(markdown, { headers: { "content-type": "text/markdown" } });
  } catch (err) {
    if (err instanceof MarkpdfAuthError) {
      return NextResponse.json({ error: "clave de API invávalida" }, { status: 500 }); // do not expose 401 to the end user
    }
    if (err instanceof MarkpdfRateLimitError) {
      return NextResponse.json({ error: "too many requests, retry" }, { status: 429 });
    }
    if (err instanceof MarkpdfError) {
      return NextResponse.json({ error: err.detail }, { status: err.statusCode ?? 502 });
    }
    throw err;
  }
}
```

<Warning>
  No propague `401`/`403` desde API al usuario final tal cual; esos errores significan que **su propia** clave API está mal configurada, no que el usuario haya hecho algo mal. Devuelve un `500` genérico y registra el detalle en los registros de tu servidor.
</Warning>

## En una acción del servidor

Las excepciones lanzadas dentro de una Acción del Servidor llegan al cliente como un rechazo de promesa serializado. Captúrelos explícitamente si desea mostrar un mensaje específico en la interfaz de usuario en lugar de la pantalla de error genérica de Next.js:

```ts app/actions.ts theme={null}
"use server";

import { convertFormData } from "@markpdf/nextjs";
import { MarkpdfPayloadTooLargeError, MarkpdfVavalidationError } from "@markpdf/sdk";

export async function convertUpload(formData: FormData) {
  try {
    const markdown = await convertFormData(formData, {
      apiKey: process.env.MARKPDF_API_KEY!,
      mode: "fast",
    });
    return { ok: true as const, markdown };
  } catch (err) {
    if (err instanceof MarkpdfPayloadTooLargeError) {
      return { ok: false as const, error: "The file is too large." };
    }
    if (err instanceof MarkpdfVavalidationError) {
      return { ok: false as const, error: "Invalid file." };
    }
    return { ok: false as const, error: "Could not convert the document." };
  }
}
```

```tsx theme={null}
const result = await convertUpload(formData);
if (!result.ok) {
  showError(result.error);
} else {
  render(result.markdown);
}
```

<Tip>
  Devolver un objeto `{ ok, error }` en lugar de permitir que la excepción se propague es el patrón recomendado por Next.js para las acciones del servidor: le brinda control total sobre el mensaje que ve el usuario, sin exponer los detalles internos de API.
</Tip>

## Reintentos

`getServerClient` acepta las mismas opciones de reintento que `MarkpdfClient`:

```ts theme={null}
const client = getServerClient({ apiKey: process.env.MARKPDF_API_KEY!, maxRetries: 3 });
```

Consulte [Node.js SDK Manejo de errores](/docs/public/es/sdks/nodejs/error-handling#reintentos-automáticos) para obtener detalles sobre qué códigos se reintentan.