Error handling

@markpdf/nextjs reuses exceptions from @markpdf/sdk (MarkpdfAuthError, MarkpdfRateLimitError, etc.), all children of MarkpdfError. How you handle them depends on whether you are in a Route Handler or a Server Action.

In a Route Handler

createConvertRouteHandler already translates any MarkpdfError into a HTTP response with the same status code and a body { error: string }:

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

If you build your own Route Handler with getServerClient, capture it yourself:

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

Don’t propagate 401/403 from the API to the end user as is — those errors mean that your own API key is misconfigured, not that the user did something wrong. Return a generic 500 and record the detail in your server logs.

In a Server Action

Exceptions thrown within a Server Action arrive to the client as a serialized promise rejection. Capture them explicitly if you want to display a specific message in the UI instead of the generic Next.js error screen:

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

Returning a { ok, error } object instead of letting the exception propagate is the pattern recommended by Next.js for Server Actions — it gives you full control over what message the user sees, without exposing internal details of the API.

Reintentos

getServerClient accepts the same retry options as MarkpdfClient:

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

See Node.js SDK Error Handling for details on which codes are retried.

Python

Node.js / TypeScript

C++

Next.js

Angular

React

React Native

Svelte

Bun

Flutter

Java

Kotlin

Error handling

Error handling

In a Route Handler

In a Server Action

Reintentos

​Error handling

​In a Route Handler

​In a Server Action

​Reintentos

Error handling

In a Route Handler

In a Server Action

Reintentos