> ## 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.

# Errors

> Error handling in the Encore Flutter SDK: errors as values on the result, plus the platform exceptions the plugin can raise

The SDK reports failures as **values**, not exceptions. `show()` never throws on iOS or Android, so a missing `try`/`catch` can't break an integration. There is no typed error class in Dart: a native failure arrives as an `errorType` string plus a human-readable `errorMessage`.

## errorType values

`errorType` is the stable identifier from the native SDKs' shared error vocabulary.

| `errorType`         | Cause                                                                                                     |
| ------------------- | --------------------------------------------------------------------------------------------------------- |
| `not_configured`    | A method was called before `configure()`                                                                  |
| `invalid_api_key`   | Empty or malformed API key                                                                                |
| `invalid_url`       | Internal URL construction failure                                                                         |
| `http_error`        | Non-2xx HTTP response                                                                                     |
| `api_error`         | The API returned a structured error                                                                       |
| `decoding_error`    | A response failed to decode                                                                               |
| `network_error`     | Connectivity issue: timeout, DNS, and so on                                                               |
| `persistence_error` | Local storage read or write failure                                                                       |
| `domain_error`      | A business rule was violated. Android also reports any unexpected native failure during `show()` this way |
| `unknown_error`     | A failure iOS could not classify. iOS only                                                                |

## Where errors arrive

### Presentation failures

A failure that stopped the sheet from appearing lands on the [`EncorePresentationResult`](./presentation-result) as `EncoreNotPresented` with `reason == EncoreNotPresentedReason.error`:

```dart theme={null}
final result = await Encore.placement('cancel_flow').show();

if (result case EncoreNotPresented(:final reason, :final errorType, :final errorMessage)) {
  if (reason == EncoreNotPresentedReason.error) {
    debugPrint('Encore: $errorType $errorMessage');
  }
  proceedWithCancellation(); // run your fallback either way
}
```

<Warning>
  Do not gate your fallback on the error branch. `EncoreNotPresented` also covers `noOffers`, `experimentControl`, and `useCaseUnavailable`, none of which are failures, and all of which still need your original flow to continue.
</Warning>

### Claim failures

A claim that errored *after* the sheet appeared surfaces on the advertiser funnel instead, as `EncoreAdvertiserFailed` with its own `errorType` and `errorMessage`. The user never saw it.

### Purchase failures

Throwing from your [purchase controller](./purchase-controller) records `EncorePublisherOutcome.failed`, and the flow continues. Return `EncorePurchaseResult.cancelled` for a user cancellation and `EncorePurchaseResult.pending` for a deferred purchase rather than throwing either.

## Platform exceptions

The methods other than `show()` are thin calls over a platform channel, and can raise a `PlatformException` for integration faults:

| Code           | Cause                                                                                     |
| -------------- | ----------------------------------------------------------------------------------------- |
| `INVALID_ARGS` | A required argument was missing on the channel. The typed Dart API normally prevents this |
| `NO_CONTEXT`   | Android only: the plugin was called before it was attached to a Flutter engine            |

Calling the plugin on web or desktop throws `MissingPluginException`, because the plugin implements iOS and Android only.

## Related

* [EncorePresentationResult](./presentation-result): where presentation and claim failures land
* [EncorePurchaseController](./purchase-controller): purchase-side failures
* Platform detail: [iOS errors](/publishers/ios/sdk-reference/errors) and [Android errors](/publishers/android/sdk-reference/errors)