Kotlin SDK - Error Handling

All SDK exceptions extend NexusException, which extends RuntimeException. You can catch the base class to handle all SDK errors in one place, or catch specific subclasses for fine-grained control.

Exception reference

Exception	When it is thrown	Thrown by
`NexusException`	Base class for all SDK errors. Also thrown directly for unexpected HTTP status codes.	Various
`NexusConfigException`	A `NexusConfig` value was rejected at construction. The message names the option, the value and - for a list option - the index. Covers a non-`https` `baseUrl`, a non-positive `ttl`, a blank or missing `apiKey`, and an `sseReconnectCooldown` entry below one minute.	`NexusClient.create`
`NexusInitException`	Initial sync failed at client creation. Wraps the underlying cause.	`NexusClient.create`
`NexusClosedException`	The client has been closed. Cached reads still work; anything touching the network does not.	`sync`, `connectStream`, the write methods
`NexusNoHttpEngineException`	No Ktor client engine is available. The message names the dependency line to add.	`NexusClient.create`
`NexusUnauthorizedException`	HTTP 401 - invalid API key, endpoint mismatch, or expired session that could not be refreshed.	`sync`, `NexusClient.create`
`NexusNotFoundException`	HTTP 404 - the service or secret was not found. Usually indicates a wrong `baseUrl`.	every endpoint
`NexusForbiddenException`	HTTP 403 - this key is not permitted to perform the operation. (On `evaluateAB`, 403 is `NexusAbAddonNotAvailableException` instead.)	every endpoint except `evaluateAB`
`NexusResponseTooLargeException`	A response body exceeded the SDK’s size cap. The cap is enforced while reading, so an over-large body never reaches the parser as a truncated document.	`sync`, `evaluateAB`, token exchange
`NexusPublicKeyException`	A public key (`wxp_…`, browser/frontend, safe to expose) was used to read or write a secret. Public keys cannot access secrets.	`getSecret`, `getSecretFilePath`, the write methods
`NexusSecretNotFoundException`	The requested secret key is not in the current snapshot.	`getSecret`, `getSecretFilePath`
`NexusBillingException`	HTTP 402 - the tenant has overdue invoices. The background refresh backs off for five minutes and cached values keep being served; `observer.onBillingOverdue()` is also called. Any successful sync clears the state.	every endpoint
`NexusServiceKindMismatchException`	A secret was read on a `frontend` service, which never syncs secrets. A path is the secret’s contents, so this applies to `getSecretFilePath` too.	`getSecret`, `getSecretFilePath`
`NexusWifNotConfiguredException`	WIF is enabled but no credential could be resolved for the current environment, The client is not created - it never falls back to API-key authentication.	`NexusClient.create`
`NexusWifTokenExchangeFailedException`	The OIDC token was obtained but the `POST /v1/auth/token-exchange` request failed.	`NexusClient.create`, background session refresh
`NexusSessionExpiredException`	WIF session expired and the background refresh failed.	Background session refresh
`NexusAbAddonNotAvailableException`	HTTP 403 from `evaluateAB` - the A/B add-on is not active for this project.	`evaluateAB`
`NexusQuarantinedException`	HTTP 429 with a quarantine payload - the service is temporarily barred from calling the API. Contains `reason: String` and `expiresAt: Instant`, already clamped to at most 24 hours from now.	every endpoint
`NexusRateLimitedException`	HTTP 429 without a quarantine payload. The request was rejected due to rate limiting; retry after a back-off.	every endpoint

One mapping, every endpoint

Since v0.11.0 a single status-to-exception mapping is shared by /v1/sync, /v1/flags/evaluate-ab and the three secret-write endpoints, so the same server response produces the same exception type whichever call made it:

Status	Exception
401	`NexusUnauthorizedException`
402	`NexusBillingException`
403	`NexusForbiddenException` - except on `evaluateAB`, where it is `NexusAbAddonNotAvailableException`
404	`NexusNotFoundException`
429 with a quarantine body	`NexusQuarantinedException`
429 without one	`NexusRateLimitedException`
anything else	`NexusException` with the endpoint and status in the message

Catching exceptions at client creation

val client = try {
    NexusClient.create(config)
} catch (e: NexusInitException) {
    // initial sync failed - could be network, DNS, or server error
    logger.error("Could not connect to Nexus", e)
    exitProcess(1)
} catch (e: NexusUnauthorizedException) {
    // bad API key or wrong baseUrl
    logger.error("Nexus auth failed - check NEXUS_API_KEY and baseUrl")
    exitProcess(1)
} catch (e: NexusNotFoundException) {
    // baseUrl points to a non-existent service
    logger.error("Nexus service not found - check baseUrl")
    exitProcess(1)
} catch (e: NexusBillingException) {
    // tenant billing overdue
    logger.warn("Nexus: billing overdue, running on last cached values")
    // continue with empty cache or exit depending on your policy
}

Catching secret access errors

val secret = try {
    client.getSecret("stripe_secret_key")
} catch (e: NexusPublicKeyException) {
    // public key (wxp_) used - this is a programming error
    throw IllegalStateException("Use a secret key (wxs_) for backend services", e)
} catch (e: NexusServiceKindMismatchException) {
    // frontend service - secrets not available
    throw IllegalStateException("Frontend services cannot access secrets", e)
} catch (e: NexusSecretNotFoundException) {
    // key does not exist in the current snapshot
    logger.warn("Secret 'stripe_secret_key' not found, using env fallback")
    System.getenv("STRIPE_SECRET_KEY") ?: error("No fallback available")
}

Catching A/B errors

val results = try {
    client.evaluateAB(listOf("checkout_v2"), userId = "user-123")
} catch (e: NexusAbAddonNotAvailableException) {
    // add-on not active - fall back to default
    mapOf("checkout_v2" to false)
} catch (e: NexusException) {
    // any other SDK error
    logger.warn("evaluateAB failed: ${e.message}")
    mapOf("checkout_v2" to false)
}

Catching all SDK errors

try {
    val client = NexusClient.create(config)
    // use client
} catch (e: NexusException) {
    logger.error("Nexus SDK error: ${e.message}", e)
}

WIF-specific errors

val config = NexusConfig(
    baseUrl = "https://my-service.westyx.dev",
    wif = WifConfig(enabled = true, credential = WifCredential.Kubernetes),
)

val client = try {
    NexusClient.create(config)
} catch (e: NexusWifNotConfiguredException) {
    // Kubernetes service account token not found at expected path
    logger.error("WIF token not available: ${e.message}")
    exitProcess(1)
} catch (e: NexusWifTokenExchangeFailedException) {
    // Token obtained but exchange endpoint rejected it
    logger.error("WIF token exchange failed: ${e.message}")
    exitProcess(1)
} catch (e: NexusInitException) {
    logger.error("Nexus init failed", e.cause)
    exitProcess(1)
}

Catching write API errors

try {
    client.setSecret("stripe_webhook_secret", newValue)
} catch (e: NexusPublicKeyException) {
    // public key (wxp_) used - this is a programming error
    throw IllegalStateException("Use a secret key (wxs_) for write operations", e)
} catch (e: NexusRateLimitedException) {
    // write endpoint rate limit - back off and retry
    logger.warn("Rate limited writing secret, will retry later")
} catch (e: NexusBillingException) {
    logger.error("Nexus: billing overdue, write rejected")
} catch (e: NexusException) {
    logger.error("Unexpected error writing secret: ${e.message}", e)
}

Quarantine

When the SDK receives a quarantine response (HTTP 429 with a JSON body containing "error": "quarantined"), it throws NexusQuarantinedException from sync() and also calls observer.onQuarantined(reason, expiresAt). For the SSE stream, the quarantine is handled automatically - the stream waits until expiresAt and reconnects without consuming its failure budget. The deadline is clamped to at most 24 hours from now, and a deadline in the past collapses to now, so both the exception and the observer callback carry a bound you can schedule against.

try {
    client.sync()
} catch (e: NexusQuarantinedException) {
    println("Quarantined: ${e.reason}, lifts at ${e.expiresAt}")
    // TTL background sync will also pause until expiresAt
}

Overview

Backend SDKs

Browser SDKs

OpenFeature Providers

Kotlin SDK - Error Handling

Exception reference

One mapping, every endpoint

Catching exceptions at client creation

Catching secret access errors

Catching A/B errors

Catching all SDK errors

WIF-specific errors

Catching write API errors

Quarantine

​Exception reference

​One mapping, every endpoint

​Catching exceptions at client creation

​Catching secret access errors

​Catching A/B errors

​Catching all SDK errors

​WIF-specific errors

​Catching write API errors

​Quarantine

Exception reference

One mapping, every endpoint

Catching exceptions at client creation

Catching secret access errors

Catching A/B errors

Catching all SDK errors

WIF-specific errors

Catching write API errors

Quarantine