Errors

Karbone never throws for expected failure modes. Every SDK method is declared as context(_: Raise<KarboneError>) suspend fun ..., using Arrow’s Raise to make failure part of the return type instead of an exception.

Every KarboneError.Api also exposes code, Carbone’s own error code when the response carries one. For example a test API key may only produce PDF output: asking for DOCX yields Unexpected(status=200, code="w117", message="With a test key, you can only convert in the following format (pdf)").

The KarboneError hierarchy

Every row above except the last four (InvalidRequest, Transport, Serialization, TemplateRead) implements KarboneError.Api, which exposes status and message uniformly. message is always the raw error text from the Carbone response, never rewritten or translated — safe to log or surface as-is.

Every KarboneError has a describe(): String for a human-readable summary, useful in logs. See the API reference for the full shape of each error type.

Handling errors with Raise

The idiomatic way to call Karbone is inside a Raise<KarboneError> scope, most simply Arrow’s either:

import arrow.core.raise.either

val result = either { karbone.renders.render(template, data) } // Either<KarboneError, RenderedDocument>

result.fold(
  { error -> log.warn { "Render failed: ${error.describe()}" } },
  { document -> saveToDisk(document) },
)

recover lets you fall back to a value instead of propagating:

import arrow.core.raise.recover

suspend fun statusOrUnknown(karbone: Karbone): ApiStatus = recover({ karbone.status() }) { error ->
  ApiStatus(success = false, code = null, message = error.describe(), version = null)
}

fold runs matching success/failure handlers directly, without materializing an Either:

import arrow.core.raise.fold

fold(
  block = { karbone.templates.delete(id) },
  recover = { error -> log.warn { error.describe() } },
  transform = { log.info { "Deleted $id" } },
)

Because KarboneError is sealed, you can also when on it exhaustively wherever that reads better than Either combinators.

The blocking facade

Karbone.blocking() wraps every call with either { ... }.fold(...), throwing KarboneException on the Left side:

public class KarboneException(public val error: KarboneError) : RuntimeException(...)

error is the same KarboneError value that Raise would have raised; getMessage() is error.describe(). This is the facade to reach for from Java, or from any Kotlin code that has not adopted Raise.

Malformed on-premise tokens

carbone-ee answers a malformed bearer token with HTTP 500 and an error message containing "Invalid JSON Web Token", rather than a 401. Karbone detects that message and maps it to KarboneError.Unauthorized regardless of the HTTP status, so callers get a consistent Unauthorized for every authentication failure — missing token, forged token, or expired token — whatever status code the server happens to answer with.