Errors

EncoreError

EncoreError is a sealed, nested enum. show() never throws: presentation failures arrive as values, in .notPresented(.error(EncoreError)) on the PresentationResult (and claim failures as AdvertiserOutcome.failed(EncoreError)). Throwing APIs like revokeEntitlements() still throw an EncoreError. User dismissals and “no offers” are business outcomes, not errors; see DismissReason and NotPresentedReason.

Never block user actions on an SDK error. Always provide a fallback path so the user can complete their intended action: every non-success result, error or not, should fall through to your original flow.

Definition

public enum EncoreError: Error, LocalizedError, Sendable {
    case transport(TransportError)      // "The road is broken" — connectivity
    case `protocol`(ProtocolError)      // "The language failed" — HTTP/API
    case integration(IntegrationError)  // "SDK misused" — config/programmer error
    case domain(String)                 // Client business-rule violation (message only)

    public enum TransportError: Error, LocalizedError, Sendable {
        case network(Error)       // No connectivity, timeout, connection failed
        case persistence(Error)   // Local storage read/write failure
    }

    public enum ProtocolError: Error, LocalizedError, Sendable {
        case http(status: Int, message: String?)        // Non-2xx, body unreadable
        case api(status: Int, code: String?, message: String) // Structured server error
        case decoding(Error)                              // 2xx body didn't match schema
    }

    public enum IntegrationError: Error, LocalizedError, Sendable {
        case notConfigured    // configure() not called before use
        case invalidApiKey    // Empty / malformed API key
        case invalidURL       // Failed to construct a request URL
    }
}

Top-level cases

Case	Associated value	Meaning
`.transport(TransportError)`	nested	Connectivity layer failed (network or local persistence).
`.protocol(ProtocolError)`	nested	The request reached the server but the exchange failed (bad status, server error, or undecodable body).
`.integration(IntegrationError)`	nested	The SDK was misused or misconfigured.
`.domain(String)`	`String`	A client-side business-rule violation, carrying a human-readable message.

Nested cases

Case	Associated values	Description
`.transport(.network(Error))`	underlying `Error`	No internet, timeout, or connection failure.
`.transport(.persistence(Error))`	underlying `Error`	Local storage (cache/outbox) read or write failed.
`.protocol(.http(status:message:))`	`Int`, `String?`	Non-2xx response with an unreadable/unexpected body.
`.protocol(.api(status:code:message:))`	`Int`, `String?`, `String`	Server returned a structured error (its own domain error).
`.protocol(.decoding(Error))`	underlying `Error`	A 2xx response body didn’t match the expected schema.
`.integration(.notConfigured)`	none	`configure(apiKey:)` was not called before use.
`.integration(.invalidApiKey)`	none	The API key was empty or malformed.
`.integration(.invalidURL)`	none	The SDK could not build a valid request URL.
`.domain(String)`	`String`	Client business-rule violation; the string describes it.

Helpers

Every EncoreError conforms to LocalizedError, so errorDescription gives a developer-readable summary. transport and protocol(.decoding) errors also expose the wrapped system error via the underlying property:

if let underlying = encoreError.underlying {
    // The original URLSession / decoding error, when one exists.
}

Handling errors

show() delivers errors as values on the result:

func cancelTapped() {
    Task {
        let result = await Encore.placement("cancel_flow").show()
        if result.claim != nil || result.publisher == .purchased {
            // Read the concrete entitlement from isActive / isActivePublisher.
        } else {
            if let error = result.error {
                switch error {
                case .integration(.notConfigured):
                    assertionFailure("Call Encore.shared.configure(apiKey:) at launch")
                case .transport(.network(let underlying)):
                    Logger.log("Network error: \(underlying.localizedDescription)")
                case .protocol(.api(_, let code, let message)):
                    Logger.log("API error (\(code ?? "unknown")): \(message)")
                default:
                    Logger.log(error.errorDescription ?? "Encore error")
                }
            }
            // Always let the user proceed.
            proceedWithCancellation()
        }
    }
}

Throwing APIs like revokeEntitlements() still use do/catch:

do {
    try await Encore.shared.revokeEntitlements()
} catch let error as EncoreError {
    Logger.log(error.errorDescription ?? "Encore error")
}

DismissReason and NotPresentedReason: business outcomes (dismiss, no offers, experiment control, unsupported OS). These are not errors.
PresentationResult: the value returned by await show(), which carries any error via result.error.

The most common “failure” is not an error at all: it is the user declining an offer, recorded on the result’s dismissal axis. Every non-success result should fall through to your original flow.

iOS

Android

Web

Bridges

EncoreError

Definition

Top-level cases

Nested cases

Helpers

Handling errors

​EncoreError

​Definition

​Top-level cases

​Nested cases

​Helpers

​Handling errors

​Related Types

EncoreError

Definition

Top-level cases

Nested cases

Helpers

Handling errors

Related Types