> ## Documentation Index
> Fetch the complete documentation index at: https://docs.markpdf.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Manejo de errores

> MarkpdfError, Resultado<T, E> y estrategia de reintento en markpdf-cpp.

# Manejo de errores

`markpdf-cpp` no genera excepciones para errores API; utiliza `markpdf::Result<T, MarkpdfError>` (consulte [Referencia](/docs/public/es/sdks/cpp/reference#resultt-e)). Solo lanza `std::runtime_error` en errores de configuración (por ejemplo, falta la clave API al crear el cliente).

```cpp theme={null}
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`

```cpp theme={null}
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`

```cpp theme={null}
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

```cpp theme={null}
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:

```cpp theme={null}
opts.maxRetries = 0;
```

<Tip />

## Trabajo falvaválido

```cpp theme={null}
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";
}
```

<Warning>
  `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.
</Warning>