EncoreError

All failures the Encore SDK reports are subclasses of EncoreError, organized into four categories by cause. show() never throws: presentation failures arrive as values, in NotPresented(NotPresentedReason.Error(...)) on the PresentationResult, and claim failures as AdvertiserOutcome.Failed(error). EncoreError extends Exception because errors still travel as throwables where the platform expects them: inside the SDK, and out of your purchase controller, which throws for a real purchase failure and lands on the record as PublisherOutcome.Failed.

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`	None of its own	Failed to decode JSON response; the underlying throwable is folded into `message` and is not exposed as `cause`

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

show() never throws. A presentation-level failure arrives as NotPresented(NotPresentedReason.Error(...)), and result.error reads it directly:

lifecycleScope.launch {
    val result = Encore.placement("cancel_flow").show()

    when (val error = result.error) {
        null -> { /* no presentation-level failure; read the record */ }
        is EncoreError.Transport.Network ->
            Log.e("Encore", "Network error: ${error.cause?.message}")
        is EncoreError.Protocol.Http ->
            Log.e("Encore", "HTTP ${error.status}: ${error.body}")
        else ->
            Log.e("Encore", "Presentation failed: ${error.message}")
    }
}

A claim that errored after the sheet appeared surfaces on the advertiser axis instead, as AdvertiserOutcome.Failed(error); see PresentationResult.

In production, log result.error broadly. Only branch on specific subtypes when you handle them differently (e.g. showing a “no internet” message for Transport.Network).

PresentationResult: where result.error and AdvertiserOutcome.Failed live
EncorePurchaseController: throwing from it records PublisherOutcome.Failed

iOS

Android

Web

Bridges

Hierarchy

Error categories

Integration: SDK misuse

Protocol: response failures

Transport: infrastructure failures

Domain: business rule violations

Usage

​Hierarchy

​Error categories

​Integration: SDK misuse

​Protocol: response failures

​Transport: infrastructure failures

​Domain: business rule violations

​Usage

​Related

Hierarchy

Error categories

Integration: SDK misuse

Protocol: response failures

Transport: infrastructure failures

Domain: business rule violations

Usage

Related