Error handling

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

import tech.markpdf.MarkpdfException

try {
    val result = client.convertFile(File("report.pdf"))
} catch (e: MarkpdfException) {
    println("Conversion failed (${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:

open class MarkpdfException(
    val statusCode: Int?,
    val detail: String,
    val requestId: String? = null,
) : RuntimeException(detail)

##Catch specific exceptions

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}")
}

With `runCatching`

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

Automatic retries

OkHttp retries internally:

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.

To disable or adjust retries, inject your own OkHttpClient with a custom Interceptor when building MarkpdfClient(http = ...).

Job falvavalid

try {
    val result = client.convertFile(File("informe-grande.pdf"))
} catch (e: MarkpdfException.JobFailedException) {
    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.

Python

Node.js / TypeScript

C++

Next.js

Angular

React

React Native

Svelte

Bun

Flutter

Java

Kotlin

Error handling

Error handling

Exceptions table

With `runCatching`

Automatic retries

Job falvavalid

​Error handling

​Exceptions table

​With runCatching

​Automatic retries

​Job falvavalid

Error handling

Exceptions table

With `runCatching`

Automatic retries

Job falvavalid