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

# EncoreError

> Structured error hierarchy for the Encore SDK

All errors thrown by the Encore SDK are subclasses of `EncoreError`, organized into four categories by cause.

## Hierarchy

```kotlin theme={null}
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

```kotlin theme={null}
lifecycleScope.launch {
    try {
        val result = Encore.placement("cancel_flow").show()
        // 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}")
    }
}
```

<Tip>
  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`).
</Tip>