All errors thrown by the Encore SDK are subclasses of EncoreError, organized into four categories by cause.
Hierarchy
sealed class EncoreError(message: String, cause: Throwable? = null) : Exception
sealed class Integration(message: String) : EncoreError
data object NotConfigured : Integration
data object InvalidApiKey : Integration
data object InvalidUrl : Integration
sealed class Protocol(message: String) : EncoreError
class Http(status: Int, body: String?) : Protocol
class Api(status: Int, code: String?, message: String) : Protocol
class Decoding(cause: Throwable) : Protocol
sealed class Transport(message: String, cause: Throwable?) : EncoreError
class Network(cause: Throwable) : Transport
class Persistence(cause: Throwable) : Transport
class Domain(message: String) : EncoreError
Error Categories
Integration — SDK misuse
Errors caused by incorrect SDK setup. These are preventable by following the integration guide.
| Error | Message | Cause |
|---|
NotConfigured | ”Encore SDK not configured. Call Encore.configure() before use.” | Called a method before configure() |
InvalidApiKey | ”Invalid API key. Please check your API key and try again.” | Empty or malformed API key |
InvalidUrl | ”Failed to construct a valid URL for the API request.” | Internal URL construction failure |
Protocol — response failures
Errors from the API layer — HTTP failures, malformed responses, or API-level errors.
| Error | Properties | Description |
|---|
Http | status: Int, body: String? | Non-2xx HTTP response |
Api | status: Int, code: String?, message: String | API returned a structured error |
Decoding | cause: Throwable | Failed to decode JSON response |
Transport — infrastructure failures
Errors from the network or persistence layer.
| Error | Properties | Description |
|---|
Network | cause: Throwable | Network connectivity issue (timeout, DNS, etc.) |
Persistence | cause: Throwable | Local storage read/write failure |
Domain — business rule violations
| Error | Properties | Description |
|---|
Domain | message: String | A business rule was violated |
Usage
lifecycleScope.launch {
try {
val result = Encore.placement("cancel_flow").show(activity)
// handle result
} catch (e: EncoreError.Integration.NotConfigured) {
Log.e("Encore", "SDK not configured — call configure() first")
} catch (e: EncoreError.Protocol.Http) {
Log.e("Encore", "HTTP ${e.status}: ${e.body}")
} catch (e: EncoreError.Transport.Network) {
Log.e("Encore", "Network error: ${e.cause?.message}")
} catch (e: EncoreError) {
Log.e("Encore", "Unexpected error: ${e.message}")
}
}
In production, catch EncoreError broadly and log it. Only catch specific subtypes when you need to handle them differently (e.g. showing a “no internet” message for Transport.Network).