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

# Handle Errors from the Figranium Kotlin SDK

> FigraniumException is the single error type in the Kotlin SDK. Learn its fields, SDK-generated codes, and how to branch on status or catch transport and timeout failures.

The Figranium Kotlin SDK raises one error type for every failure: `FigraniumException`. It extends `java.io.IOException`, so you can catch it alongside transport errors in a single `catch` block. You can branch on `status` for HTTP semantics, on `code` for machine-readable categories, and on `message` for a human-readable description.

## FigraniumException shape

```kotlin Figranium.kt theme={null}
class FigraniumException(
    val status: Int = 0,
    val code: String? = null,
    val details: JsonElement? = null,
    val requestId: String? = null,
    message: String
) : IOException(message)
```

Because `FigraniumException` extends `IOException`, OkHttp transport failures (such as `SocketTimeoutException` or `UnknownHostException`) and Figranium API errors can be handled together or separately depending on how you structure your catch blocks.

## Basic handling

```kotlin Client.kt theme={null}
import dev.figranium.sdk.*
import java.io.IOException

val client = Figranium(authentication = FigraniumAuthentication.ApiKey("your-api-key"))

try {
    client.runTask("missing-task")
} catch (e: FigraniumException) {
    println(e.status)      // e.g. 404
    println(e.code)        // e.g. "TASK_NOT_FOUND"
    println(e.details)     // server diagnostics
    println(e.requestId)   // when supplied by the server or proxy
} catch (e: IOException) {
    println("Transport failure: ${e.message}")
}
```

## Fields

<AccordionGroup>
  <Accordion title="`status`">
    The HTTP status returned by the Figranium server, if a response arrived. `0` when the request never reached a status, such as a network failure, DNS error, or cancelled request.
  </Accordion>

  <Accordion title="`code`">
    Server-provided machine-readable error code, taken from the response body's `error` field. Also used for SDK-generated conditions:

    | Code | Meaning |
    | :- | :- |
    | `EMPTY_RESPONSE` | The response body was empty or the server returned 204. |
    | `INVALID_RESPONSE` | The response body could not be parsed as JSON. |
    | `NETWORK_ERROR` | The stream could not be opened, or a non-Figranium error occurred during a stream request. |
  </Accordion>

  <Accordion title="`details`">
    Free-form value from the response body's `details` or `detail` field. Typically an object describing which validation failed, which record was missing, or which field was invalid.
  </Accordion>

  <Accordion title="`requestId`">
    Value of the `x-request-id` response header, when the server or a proxy sets one. Include this in bug reports to make server-side logs easier to correlate.
  </Accordion>

  <Accordion title="`message`">
    Human-readable description of what went wrong. For server errors, this is taken from the response body's `message` or `error` field. For SDK-generated errors, it describes the condition (for example, "Figranium returned an empty response").
  </Accordion>
</AccordionGroup>

## Branching on status

```kotlin Client.kt theme={null}
import dev.figranium.sdk.*

try {
    client.tasks.get("some-task-id")
} catch (e: FigraniumException) {
    when (e.status) {
        401 -> {
            // Reauthenticate or refresh the API key.
            refreshApiKey()
        }
        404 -> {
            // Task is gone; treat as an empty result.
        }
        429 -> {
            // Back off and retry.
            delay(2_000)
        }
        else -> throw e
    }
}
```

## Transport failures

When the request never gets a response (server unreachable, DNS failure, TLS error), OkHttp throws an `IOException`. Because `FigraniumException` extends `IOException`, you can handle both Figranium errors and transport errors in one catch, or distinguish them by type.

```kotlin Client.kt theme={null}
import dev.figranium.sdk.*
import java.io.IOException

try {
    client.health.check()
} catch (e: FigraniumException) {
    println("Figranium API error: ${e.message}")
} catch (e: IOException) {
    println("Figranium is unreachable: ${e.message}")
}
```

## Timeouts and cancellation

When a request exceeds the configured timeout, the underlying `OkHttpClient` throws an `IOException` (such as `SocketTimeoutException`). When the consuming coroutine is cancelled, the active `Call` is cancelled and a `CancellationException` is thrown.

```kotlin Client.kt theme={null}
import dev.figranium.sdk.*
import java.io.IOException
import kotlinx.coroutines.CancellationException

try {
    client.runTask("slow-task", options = RequestOptions(timeoutMillis = 5_000))
} catch (e: FigraniumException) {
    println("Figranium error: ${e.message}")
} catch (e: CancellationException) {
    println("The request was cancelled")
} catch (e: IOException) {
    println("The request timed out or the network failed: ${e.message}")
}
```

Cancelling the consumer of a flow stream also cancels the underlying `Call`.

<Tip>
  Always check `e is FigraniumException` before reading SDK-specific fields. Unknown errors should be rethrown so they bubble up to your global error handler.
</Tip>

<CardGroup cols={2}>
  <Card title="Request Options" icon="sliders" href="/docs/sdk/kotlin/request-options">
    Set per-call timeouts and headers.
  </Card>

  <Card title="Streaming" icon="activity" href="/docs/sdk/kotlin/streaming">
    Consume Server-Sent Events and handle stream-specific errors.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.