> ## 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

> Kotlin SDK excepciones escritas y estrategia de reintento.

# Manejo de errores

SDK traduce cada código de error HTTP en una subclase anidada de `MarkpdfException` (`RuntimeException`).

```kotlin theme={null}
import tech.markpdf.MarkpdfException

try {
    val result = client.convertFile(File("report.pdf"))
} catch (e: MarkpdfException) {
    println("Conversion failed (${e.statusCode}): ${e.detail}")
}
```

## Tabla de excepciones

| Estado HTTP | Clase                                        | causa                                                              |
| ----------: | -------------------------------------------- | ------------------------------------------------------------------ |
|     — (red) | `MarkpdfException.ConnectionException`       | No se pudo conectar, se agotó el tiempo de espera o `IOException`. |
|       `400` | `MarkpdfException.BadRequestException`       | Cuerpo inválido o URL malformado.                                  |
|       `401` | `MarkpdfException.AuthenticationException`   | Falta la clave API o no es válida.                                 |
|       `403` | `MarkpdfException.ForbiddenException`        | Clave sin permiso o host no autorizado de URL.                     |
|       `413` | `MarkpdfException.PayloadTooLargeException`  | Documento, páginas o ZIP fuera de límites.                         |
|       `415` | `MarkpdfException.UnsupportedMediaException` | Formato o `content-encoding` no admitido.                          |
|       `422` | `MarkpdfException.VavalidationException`     | Faltan parámetros requeridos.                                      |
|       `429` | `MarkpdfException.RateLimitException`        | Demasiadas peticiones.                                             |
|       `5xx` | `MarkpdfException.ServerException`           | Error de conversión en el servidor.                                |
| — (trabajo) | `MarkpdfException.JobFailedException`        | El trabajo en cola (`202`) falló después de reintentos internos.   |

Todas extienden `MarkpdfException` y exponente:

```kotlin theme={null}
open class MarkpdfException(
    val statusCode: Int?,
    val detail: String,
    val requestId: String? = null,
) : RuntimeException(detail)
```

\##Capturar excepciones específicas

```kotlin theme={null}
import tech.markpdf.MarkpdfException.*

try {
    val result = client.convertFile(File("report.pdf"), ConvertOptions(mode = ConversionMode.FAST))
} catch (e: AuthenticationException) {
    throw IllegalStateException("API key invávalida", e)
} catch (e: PayloadTooLargeException) {
    println("Document too large; prueba con pages para dividirlo.")
} catch (e: RateLimitException) {
    println("Rate limited: ${e.detail}")
} catch (e: VavalidationException) {
    println("Parámetros invávavalids: ${e.detail}")
} catch (e: ServerException) {
    println("Conversion error; try mode = ConversionMode.BALANCED.")
} catch (e: MarkpdfException) {
    // catch-all for any other exceptions from SDK
    println("Error: ${e.detail}")
}
```

### Con `runCatching`

```kotlin theme={null}
val markdown = runCatching {
    client.convertFile(File("report.pdf"))
}.mapCatching { result ->
    (result as? ConvertResult.Markdown)?.markdown ?: error("unexpected response")
}.getOrElse { e ->
    when (e) {
        is RateLimitException -> "Rate limited, retry later"
        is MarkpdfException -> "Error: ${e.detail}"
        else -> throw e
    }
}
```

## Reintentos automáticos

OkHttp reintenta internamente:

* `429` y `5xx`: reintentos con retroceso exponencial y jitter. Respete `Retry-After` si el servidor lo envía.
* `4xx` diferente de `429`: **no** reintentado.
* Errores de red/tiempo de espera: reintento igual que `5xx`.

Para deshabilitar o ajustar los reintentos, inyecte su propio `OkHttpClient` con un `Interceptor` personalizado al compilar `MarkpdfClient(http = ...)`.

<Tip />

## Trabajo falvaválido

```kotlin theme={null}
try {
    val result = client.convertFile(File("informe-grande.pdf"))
} catch (e: MarkpdfException.JobFailedException) {
    println("Job ${e.jobId} falló: ${e.detail}")
}
```

<Warning>
  `JobFailedException` significa que el trabajo ya agotó los reintentos del servidor interno. Volver a intentarlo desde el cliente es razonable, pero hágalo con retroceso.
</Warning>