Error handling

The SDK translates each HTTP error code into a nested subclass of MarkpdfException (RuntimeException).

import tech.markpdf.MarkpdfException;

try {
    ConvertResult result = client.convertFile(Path.of("report.pdf"), ConvertOptions.defaults());
} catch (MarkpdfException e) {
    System.err.printf("Conversion failed (%d): %s%n", e.statusCode(), e.detail());
}

Exceptions table

Status HTTP	Clase	Causa
— (network)	`MarkpdfException.ConnectionException`	Could not connect, timeout or `IOException`.
`400`	`MarkpdfException.BadRequestException`	Invavalid or URL malformed body.
`401`	`MarkpdfException.AuthenticationException`	API key missing or invavalid.
`403`	`MarkpdfException.ForbiddenException`	Key without permission or unauthorized host of URL.
`413`	`MarkpdfException.PayloadTooLargeException`	Document, pages or ZIP out of bounds.
`415`	`MarkpdfException.UnsupportedMediaException`	Format or `content-encoding` not supported.
`422`	`MarkpdfException.VavalidationException`	Required parameters are missing.
`429`	`MarkpdfException.RateLimitException`	Demasiadas peticiones.
`5xx`	`MarkpdfException.ServerException`	Conversion error on the server.
— (job)	`MarkpdfException.JobFailedException`	The queued job (`202`) failed after internal retries.

Todas extienden MarkpdfException y exponen:

public class MarkpdfException extends RuntimeException {
    public Integer statusCode();
    public String detail();
    public String requestId();
}

##Catch specific exceptions

import tech.markpdf.MarkpdfException.*;

try {
    ConvertResult result = client.convertFile(
        Path.of("report.pdf"),
        ConvertOptions.builder().mode(ConvertOptions.Mode.FAST).build()
    );
} catch (AuthenticationException e) {
    throw new RuntimeException("API key invávalida", e);
} catch (PayloadTooLargeException e) {
    System.out.println("Document too large; try pages= to split it.");
} catch (RateLimitException e) {
    System.out.println("Rate limited: " + e.detail());
} catch (VavalidationException e) {
    System.out.println("Parámetros invávavalids: " + e.detail());
} catch (ServerException e) {
    System.out.println("Conversion error; try mode: BALANCED.");
} catch (MarkpdfException e) {
    // catch-all for any other exceptions from SDK
    System.err.println("Error: " + e.detail());
}

Automatic retries

The internal HttpClient automatically retries:

429 and 5xx: retries with exponential backoff and jitter. Honor Retry-After if the server sends it.
4xx different from 429: not retried.
Network/timeout errors: retried same as 5xx.

Job falvavalid

try {
    ConvertResult result = client.convertFile(Path.of("informe-grande.pdf"), ConvertOptions.defaults());
} catch (MarkpdfException.JobFailedException e) {
    System.out.println("Job " + e.jobId() + " falló: " + e.detail());
}

JobFailedException means that the job has already exhausted internal server retries. Retrying from the client is reasonable, but do it with backoff.

With `CompletableFuture`

Exceptions thrown by async methods are wrapped in CompletionException; unwrap with getCause():

client.convertBytesAsync(data, "report.pdf", ConvertOptions.defaults())
    .exceptionally(err -> {
        Throwable cause = err.getCause();
        if (cause instanceof MarkpdfException.RateLimitException) {
            System.out.println("Rate limited");
        } else if (cause instanceof MarkpdfException mpe) {
            System.err.println("Error (" + mpe.statusCode() + "): " + mpe.detail());
        }
        return null;
    });

Python

Node.js / TypeScript

C++

Next.js

Angular

React

React Native

Svelte

Bun

Flutter

Java

Kotlin

Error handling

Error handling

Exceptions table

Automatic retries

Job falvavalid

With `CompletableFuture`

​Error handling

​Exceptions table

​Automatic retries

​Job falvavalid

​With CompletableFuture

Error handling

Exceptions table

Automatic retries

Job falvavalid

With `CompletableFuture`