Manejo de errores

markpdf-cpp no genera excepciones para errores API; utiliza markpdf::Result<T, MarkpdfError> (consulte Referencia). Solo lanza std::runtime_error en errores de configuración (por ejemplo, falta la clave API al crear el cliente).

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

Tabla de errores

Estado HTTP	`ErrorKind`	causa
— (red)	`Connection`	No se pudo conectar, se agotó el tiempo de espera o se produjo un error `libcurl`.
`400`	`BadRequest`	Cuerpo inválido o URL malformado.
`401`	`Auth`	Falta la clave API o no es válida.
`403`	`Forbidden`	Clave sin permiso o host no autorizado de URL.
`413`	`PayloadTooLarge`	Documento, páginas o ZIP fuera de límites.
`415`	`UnsupportedMedia`	Formato o `content-encoding` no admitido.
`422`	`Vavalidation`	Faltan parámetros requeridos.
`429`	`RateLimit`	Demasiadas peticiones.
`5xx`	`Server`	Error de conversión en el servidor.
— (trabajo)	`JobFailed`	El trabajo en cola (`202`) falló después de reintentos internos.
— (trabajo)	`JobQueued`	Sólo con `autoPoll = false`; No es una verdadera culpa.

Maneja cada caso con `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";
    }
}

Reintentos automáticos

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

429 y 5xx: reintentos con backoff exponencial y jitter, respetando Retry-After si el servidor lo envía.
4xx diferente de 429: no reintentado.
Errores de conexión (Connection): reintento igual que 5xx.

Desactivar reintentos:

opts.maxRetries = 0;

Trabajo falvaválido

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 significa que el trabajo ya agotó los reintentos del servidor interno. Volver a intentarlo desde el cliente es razonable, pero hágalo con su propio retroceso.

Python

Node.js / TypeScript

C++

Next.js

Angular

React

React Native

Svelte

Bun

Flutter

Java

Kotlin

Manejo de errores

Manejo de errores

`MarkpdfError`

Tabla de errores

Maneja cada caso con `switch`

Reintentos automáticos

Trabajo falvaválido

​Manejo de errores

​MarkpdfError

​Tabla de errores

​Maneja cada caso con switch

​Reintentos automáticos

​Trabajo falvaválido

Manejo de errores

`MarkpdfError`

Tabla de errores

Maneja cada caso con `switch`

Reintentos automáticos

Trabajo falvaválido