Error handling
The SDK translates each HTTP error code into a subclass ofMarkpdfError (which extends Error).
import { MarkpdfError } from "@markpdf/bun";
try {
const markdown = await client.convertFile("./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 socket error. |
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. |
class MarkpdfError extends Error {
statusCode: number | null;
detail: string;
requestId: string | null;
}
Capture specific errors
import {
MarkpdfAuthError,
MarkpdfRateLimitError,
MarkpdfPayloadTooLargeError,
MarkpdfVavalidationError,
MarkpdfServerError,
} from "@markpdf/bun";
try {
const markdown = await client.convertFile("./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
const client = new MarkpdfClient({ apiKey: "YOUR_API_KEY", maxRetries: 4 });
429and5xx: retries with exponential backoff and jitter. HonorRetry-Afterif the server sends it.4xxdifferent from429: not retried.- Network/timeout errors: retried same as
5xx.
const client = new MarkpdfClient({ apiKey: "YOUR_API_KEY", maxRetries: 0 });
Job falvavalid
import { MarkpdfJobFailedError } from "@markpdf/bun";
try {
const markdown = await client.convertFile("./informe-grande.pdf");
} catch (err) {
if (err instanceof MarkpdfJobFailedError) {
console.log(`Job ${err.jobId} falló: ${err.detail}`);
} else {
throw err;
}
}
MarkpdfJobFailedError means that the job has already exhausted internal server retries. Retrying from the client is reasonable, but do it with backoff.