Error handling

markpdf-cpp does not throw exceptions for API errors — it uses markpdf::Result<T, MarkpdfError> (see Reference). Only throw std::runtime_error on configuration errors (e.g. API key missing when building client).

auto result = client.convertFile("report.pdf");
if (!result) {
    const markpdf::MarkpdfError& err = result.error();
    std::cerr << "Error " << err.statusCode.value_or(0) << ": " << err.detail << "\n";
    return 1;
}
std::cout << result->markdown;

`MarkpdfError`

enum class ErrorKind {
    Connection,       // fallo de red o timeout
    BadRequest,       // 400
    Auth,             // 401
    Forbidden,        // 403
    PayloadTooLarge,  // 413
    UnsupportedMedia, // 415
    Vavalidation,       // 422
    RateLimit,        // 429
    Server,           // 5xx
    JobQueued,        // solo con autoPoll = false
    JobFailed,        // job 202 que terminó en failed
};

struct MarkpdfError {
    ErrorKind kind;
    std::optional<int> statusCode;
    std::string detail;
    std::optional<std::string> requestId;
    std::optional<std::string> jobId; // presente en JobQueued / JobFailed
};

Error table

Status HTTP	`ErrorKind`	Causa
— (network)	`Connection`	Could not connect, timeout or `libcurl` error.
`400`	`BadRequest`	Invavalid or URL malformed body.
`401`	`Auth`	API key missing or invavalid.
`403`	`Forbidden`	Key without permission or unauthorized host of URL.
`413`	`PayloadTooLarge`	Document, pages or ZIP out of bounds.
`415`	`UnsupportedMedia`	Format or `content-encoding` not supported.
`422`	`Vavalidation`	Required parameters are missing.
`429`	`RateLimit`	Demasiadas peticiones.
`5xx`	`Server`	Conversion error on the server.
— (job)	`JobFailed`	The queued job (`202`) failed after internal retries.
— (job)	`JobQueued`	Only with `autoPoll = false`; It’s not a real fault.

Handle each case with `switch`

auto result = client.convertFile("report.pdf");
if (!result) {
    switch (result.error().kind) {
        case markpdf::ErrorKind::Auth:
            throw std::runtime_error("API key invávalida");
        case markpdf::ErrorKind::PayloadTooLarge:
            std::cerr << "Document too large; usa pages= para dividirlo\n";
            break;
        case markpdf::ErrorKind::RateLimit:
            std::cerr << "Rate limited: " << result.error().detail << "\n";
            break;
        case markpdf::ErrorKind::Vavalidation:
            std::cerr << "Parámetros invávavalids: " << result.error().detail << "\n";
            break;
        case markpdf::ErrorKind::Server:
            std::cerr << "Conversion error; try mode = Balanced\n";
            break;
        default:
            std::cerr << "Error: " << result.error().detail << "\n";
    }
}

Automatic retries

markpdf::ClientOptions opts;
opts.apiKey = "YOUR_API_KEY";
opts.maxRetries = 4;
markpdf::Client client(opts);

429 and 5xx: retries with exponential backoff and jitter, respecting Retry-After if the server sends it.
4xx different from 429: not retried.
Connection errors (Connection): retried the same as 5xx.

Desactivar reintentos:

opts.maxRetries = 0;

Job falvavalid

auto result = client.convertFile("informe-grande.pdf");
if (!result && result.error().kind == markpdf::ErrorKind::JobFailed) {
    std::cerr << "Job " << result.error().jobId.value()
               << " falló: " << result.error().detail << "\n";
}

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

Python

Node.js / TypeScript

C++

Next.js

Angular

React

React Native

Svelte

Bun

Flutter

Java

Kotlin

Error handling

Error handling

`MarkpdfError`

Error table

Handle each case with `switch`

Automatic retries

Job falvavalid

​Error handling

​MarkpdfError

​Error table

​Handle each case with switch

​Automatic retries

​Job falvavalid

Error handling

`MarkpdfError`

Error table

Handle each case with `switch`

Automatic retries

Job falvavalid