Per-Request Options in the Figranium Kotlin SDK

Every SDK method accepts an optional options argument that controls per-call timeouts and one-off headers. The same RequestOptions shape works for regular requests and for Kotlin Flow streams.

RequestOptions

import dev.figranium.sdk.*

val options = RequestOptions(
    headers = mapOf("x-correlation-id" to "req-42"),
    timeoutMillis = 10_000
)

RequestOptions is a data class with two optional fields:

Field	Type	Description
`headers`	`Map<String, String>`	Extra headers merged over the client’s default headers for this call.
`timeoutMillis`	`Long?`	Overrides the client-wide default timeout for this call, in milliseconds. Streams default to no timeout when `null`.

Override timeout per call

Use timeoutMillis to set a shorter or longer bound for a single request.

Client.kt

import dev.figranium.sdk.*

val client = Figranium(
    authentication = FigraniumAuthentication.ApiKey(System.getenv("FIGRANIUM_API_KEY")!!)
)

// Use a 5-second timeout for this call only
client.tasks.list(options = RequestOptions(timeoutMillis = 5_000))

The client-wide default is 30_000 milliseconds. See Client configuration for setting the default.

Inject one-off headers

Use headers to add request correlation IDs, feature flags, or override a default value once.

Client.kt

client.tasks.list(
    options = RequestOptions(headers = mapOf("x-correlation-id" to "req-42"))
)

Combining options

Pass both fields together when needed:

Client.kt

client.tasks.save(
    task = task,
    createVersion = true,
    options = RequestOptions(
        timeoutMillis = 10_000,
        headers = mapOf("x-run-id" to "run-123")
    )
)

Header merge order

The SDK builds the final header set in this order. Each step can overwrite the previous one:

Client default headers (headers passed to the constructor)
accept: application/json (regular requests) or accept: text/event-stream (streams)
Per-call options.headers
Authentication header (Authorization or x-api-key) from FigraniumAuthentication

Timeout and cancellation semantics

When a request exceeds the configured timeout, the underlying OkHttpClient throws an IOException (for example, java.net.SocketTimeoutException). FigraniumException extends IOException, so transport failures surface naturally through the same catch block. When the consuming coroutine is cancelled, the active Call is cancelled automatically and the flow or suspend function throws a CancellationException.

Client.kt

import dev.figranium.sdk.*
import java.io.IOException

val client = Figranium(
    authentication = FigraniumAuthentication.ApiKey(System.getenv("FIGRANIUM_API_KEY")!!)
)

try {
    client.runTask("slow-task", options = RequestOptions(timeoutMillis = 5_000))
} catch (e: FigraniumException) {
    println("Figranium error: ${e.message}")
} catch (e: IOException) {
    println("Network or timeout failure: ${e.message}")
}

Stream timeouts

Streams have no default timeout. Pass options = RequestOptions(timeoutMillis = 60_000) when you want a terminal deadline. The underlying OkHttpClient cancel or timeout will surface as an IOException.

Client.kt

client.executions.stream(options = RequestOptions(timeoutMillis = 60_000))
    .collect { event ->
        println(event.data)
    }

See Streaming for more on consuming SSE events.

Use timeoutMillis for hard deadlines on individual requests. For long-running streams, prefer cancelling the consuming coroutine scope so you can stop cleanly when your application state changes.

Client Configuration

Set client-wide defaults for timeout, headers, and auth.

Errors

Learn how FigraniumException and transport failures are surfaced.

Introduction

JavaScript SDK

Python SDK

Swift SDK

Kotlin SDK

Per-Request Options in the Figranium Kotlin SDK

RequestOptions

Override timeout per call

Inject one-off headers

Combining options

Header merge order

Timeout and cancellation semantics

Stream timeouts

Client Configuration

Errors

​RequestOptions

​Override timeout per call

​Inject one-off headers

​Combining options

​Header merge order

​Timeout and cancellation semantics

​Stream timeouts

Client Configuration

Errors

RequestOptions

Override timeout per call

Inject one-off headers

Combining options

Header merge order

Timeout and cancellation semantics

Stream timeouts