Error handling

With `useConvertFile`

The hook never throws inside the component — errors remain in the error state field, as instances of MarkpdfError (the same class as SDK base):

const { convert, status, error } = useConvertFile();

if (status === "error" && error) {
  return <p>Error {error.statusCode}: {error.detail}</p>;
}

convert() also rejects the promise it returns, so you can capture it there if you prefer try/catch instead of reading error from the state:

try {
  await convert(file);
} catch (err) {
  // same object that ended in `error`
}

With raw client (`useMarkpdf`)

The useMarkpdf() methods (convertFile, convertFromUrl, convertStream, pdfIndex, getJob) launch typed subclasses of MarkpdfError, just as in Node.js:

import { useMarkpdf } from "@markpdf/react";
import { MarkpdfAuthError, MarkpdfPayloadTooLargeError, MarkpdfRateLimitError } from "@markpdf/sdk";

function Convert({ url }: { url: string }) {
  const client = useMarkpdf();

  const run = async () => {
    try {
      const markdown = await client.convertFromUrl(url, { mode: "fast" });
      console.log(markdown);
    } catch (err) {
      if (err instanceof MarkpdfAuthError) {
        console.error("API key invávalida");
      } else if (err instanceof MarkpdfPayloadTooLargeError) {
        console.error("Document too large");
      } else if (err instanceof MarkpdfRateLimitError) {
        console.error("Rate limited, retry later");
      } else {
        throw err;
      }
    }
  };

  return <button onClick={run}>Convertir</button>;
}

See the full error table of the base SDK — the same applies here because @markpdf/react re-exports the same classes.

Reusable error component

import { MarkpdfError } from "@markpdf/sdk";

function ConversionError({ error }: { error: MarkpdfError }) {
  const messages: Record<number, string> = {
    401: "API key invávalida o ausente.",
    413: "The document is too large. Try pages= to split it.",
    422: "Required parameters are missing.",
    429: "Demasiadas peticiones, intenta de nuevo en unos segundos.",
    500: "Conversion error. Try mode: 'balanced'.",
  };

  return <p role="alert">{messages[error.statusCode ?? 0] ?? error.message}</p>;
}

useConvertFile does not automatically retry. If you want retries with backoff at 429/5xx, use the base client (useMarkpdf()) with maxRetries — see Node.js SDK Error Handling — instead of useConvertFile, or implement your own retry around convert().