Error Handling - Encore SDK

The Web SDK reports errors as values, not exceptions.

show() and redeem() never reject: any failure (SDK not configured, network error, unexpected exception) resolves as { status: 'dismissed', reason: { type: 'error', error } }. No try/catch needed.
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}`);
}

For redeem(), an error result leaves the pending transaction untouched, so calling redeem() again later is safe. ({ status: 'none' } is never an error: it strictly means there was nothing pending to redeem.)

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, incl. remote config unreachable at the deferred pre-flight
  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
  CONFIGURATION_ERROR = 'CONFIGURATION_ERROR', // invalid SDK configuration, incl. required display values unresolved
  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.

The deferred pre-flight pair

A deferred show() checks the required host display values before any analytics or UI, and distinguishes two failure classes in its dismissed result:

CONFIGURATION_ERROR: the remote config loaded but a required field is genuinely absent. The message names each missing field with its fixes (pass it in display.*, or set it in the Encore portal). Fix the integration; retrying won’t help.
NETWORK_ERROR: the remote config was unreachable, so requiredness couldn’t be judged. Transient: the next show() call retries the fetch.

show() · redeem(): the never-rejects result contracts
configure(): validation behavior
Display Resolution: the pre-flight’s value chain in full

​Reading an error from a result

​EncoreError

​ErrorCode

​The deferred pre-flight pair

​Related

Reading an error from a result

EncoreError

ErrorCode

The deferred pre-flight pair

Related