Manejo de errores

@markpdf/nextjs reutiliza excepciones de @markpdf/sdk (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 }:

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

app/api/convert/route.ts

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

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.

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:

app/actions.ts

"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." };
  }
}

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

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.

Reintentos

getServerClient acepta las mismas opciones de reintento que MarkpdfClient:

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

Consulte Node.js SDK Manejo de errores para obtener detalles sobre qué códigos se reintentan.

Python

Node.js / TypeScript

C++

Next.js

Angular

React

React Native

Svelte

Bun

Flutter

Java

Kotlin

Manejo de errores

Manejo de errores

En un controlador de ruta

En una acción del servidor

Reintentos

​Manejo de errores

​En un controlador de ruta

​En una acción del servidor

​Reintentos

Manejo de errores

En un controlador de ruta

En una acción del servidor

Reintentos