Error Handling

The Web SDK reports errors as values, not exceptions.

show() never rejects: a failure (network error, unexpected exception) resolves as { status: 'dismissed', reason: { type: 'error', error } }. No try/catch needed. Calling show() before configure() is reported by the named reason 'notConfigured' rather than a generic error. See Not-configured.
configure() returns false on invalid input (and logs the reason); it does not throw.
Fire-and-forget methods (identify(), setUserAttributes(), reset()) log errors to the console rather than throwing.

Reading an error from a result

const result = await Encore.show();

if (result.status === 'dismissed' && typeof result.reason === 'object' && result.reason.type === 'error') {
  const { code, message } = result.reason.error;
  console.error(`Offer flow failed: ${code}: ${message}`);
}

Not-configured

Calling show() before configure() is one specific integration mistake with one fix, so it gets its own reason rather than a generic error payload:

const result = await Encore.show();
// { status: 'dismissed', reason: 'notConfigured' }

show()’s options.onError also fires for it, with INITIALIZATION_ERROR.

EncoreError

interface EncoreError {
  code: ErrorCode | string;
  message: string;
  details?: unknown;
  type?: string;
  statusCode?: number;   // HTTP status, for API errors
}

ErrorCode

enum ErrorCode {
  NETWORK_ERROR = 'NETWORK_ERROR',           // connectivity failure
  TIMEOUT = 'TIMEOUT',                       // request took too long
  API_ERROR = 'API_ERROR',                   // API returned an error response
  UNAUTHORIZED = 'UNAUTHORIZED',             // invalid or revoked API key
  NOT_FOUND = 'NOT_FOUND',                   // resource not found
  INVALID_REQUEST = 'INVALID_REQUEST',       // malformed request, incl. an unrecognized useCase value
  CONFIGURATION_ERROR = 'CONFIGURATION_ERROR', // invalid SDK configuration
  INITIALIZATION_ERROR = 'INITIALIZATION_ERROR', // SDK method called before configure()
  STORAGE_ERROR = 'STORAGE_ERROR',           // localStorage/sessionStorage failure
  UNKNOWN_ERROR = 'UNKNOWN_ERROR',           // anything else
}

INITIALIZATION_ERROR is the one you’ll most likely see during integration: it means a method ran before configure() succeeded.

An unrecognized use case

INVALID_REQUEST is the one error that fires both onError and onNotGranted, and it fires before any presentation attempt. It means the useCase passed to show() or placement() was not 'reduceChurn' or 'rewardUsers'. That is an integration bug rather than a normal outcome, so don’t confuse it with the silent unavailable a valid use case with nothing to present produces. The values Encore sends over the wire are deliberately not accepted here; passing one produces exactly this error.

show(): the never-rejects result contract
configure(): validation behavior
The Claim Flow: what a successful presentation resolves to

iOS

Android

Web

Bridges

Error Handling

Reading an error from a result

Not-configured

EncoreError

ErrorCode

An unrecognized use case

​Reading an error from a result

​Not-configured

​EncoreError

​ErrorCode

​An unrecognized use case

​Related

Reading an error from a result

Not-configured

EncoreError

ErrorCode

An unrecognized use case

Related