Error handling

SDK calls return TNetworkResponse<T>. Check success before accessing result. Catch exceptions from rendering, scenario decoding, and any custom transport separately.

const response = await placeBet({ backendURL, token, stake, config });
if (!response.success) {
  stopAutoplay();
  blockPlay();
  showError(response.error.code, response.error.message);
  // Reconcile the server state before permitting another money request.
} else {
  await present(response.result);
}

Error contract

IErrorResponse contains a string code, a message, and optional passThroughData. API_RETURNCODES is a numeric enum. Convert its value to a string before comparison.

if (!response.success && response.error.code === String(API_RETURNCODES.REALITYCHECK)) {
  // Keep the next paid action blocked until the operator flow completes.
}

recoverableErrorCodes already contains strings. The default network timeout is 30,000 milliseconds.

Do not expose tokens, complete requests, or raw session data in logs. Retain safe diagnostic identifiers, the error code, operation, timestamp, and last known round hash.

Controller and loader errors

The controller and loader examples throw SdkRequestError for an SDK failure. It retains code, passThroughData, and the original error as cause.

Download the error helper. Save it beside the other example files.

import type { IErrorResponse } from '@hizi.io/engine-sdk';

// Keep SDK failures distinguishable from validation and renderer exceptions.
export class SdkRequestError extends Error {
  readonly code: IErrorResponse['code'];
  readonly passThroughData: IErrorResponse['passThroughData'];

  constructor(error: IErrorResponse) {
    super(error.message, { cause: error });
    this.name = 'SdkRequestError';
    this.code = error.code;
    this.passThroughData = error.passThroughData;
  }
}

import { SdkRequestError } from './sdk-error';

try {
  await game.start(selectedStake);
} catch (error) {
  stopAutoplay();
  blockPlay();
  if (error instanceof SdkRequestError) {
    handleOperatorError(error.code, error.message, error.passThroughData);
  } else {
    showLocalError(error);
  }
}

The handlers are application components. Validate operator data before displaying a dialog or sending an acknowledgement. Keep play blocked until recovery completes.

Recovery policy

Error	Action
BALANCETOOLOW	Stop autoplay. Refresh balance. Offer the approved cashier action.
BETLIMITREACHED, INVALIDPARAMETER	Revalidate stakes and settings. Do not keep sending the rejected value.
NETWORKERROR, malformed response, or lost connection	Treat the transaction outcome as unknown. Reconnect and load current state.
OPERATIONBEINGPROCESSED	Keep actions blocked. Poll a safe state read with bounded delay. Do not submit another bet.
RATELIMITEXCEEDED	Stop repeated requests. Use bounded backoff for safe reads. Reconcile any money action.
GENERICBETERROR, GENERICWINERROR, RNGFAILURE	Display the failure. Determine round state before any new action.
SESSIONINVALID, NOTLOGGEDON	Use the supplied refresh flow when allowed. Replace session data and restore the round.
PLAYERBLOCKED, COOLOFFPERIODACTIVE, RESPONSIBLEGAMINGLIMITREACHED, RESPONSIBLESGAMINGSESSIONEXPIRED, or REALITYCHECK	Follow the operator's dialog and acknowledgement contract. Do not automatically retry.
Unknown code or inconsistent state	Stop new play. Preserve the last confirmed state and offer support or exit.

The exported recoverableErrorCodes list classifies errors. It does not guarantee that retrying a money request is safe.

A bet can commit before the connection fails. Neither placeBet nor collect exposes a general client idempotency key. Never turn a Retry button into an unconditional repeat of the last request.

Use recovery to discover whether the round is open, complete, or awaiting a choice. A new paid bet requires a new player action.

Operator errors and messages

Honor operatorHandlesErrors and translateErrors. Forward required errors through Operator Interface.

Preserve passThroughData for the operator adapter. It can include a dialog, buttons, or an acknowledgement requirement. Do not reduce every error to a generic dismiss button.

Render message text safely. Validate button URLs and allowed actions. Do not evaluate response content as code or insert arbitrary HTML.

A dismissed dialog does not clear an uncertain transaction. Keep separate blocks for operator pause, session expiry, recovery, and responsible-gambling restrictions.

Recovery UX

Show the last confirmed board with a clear pending or reconnecting state. Avoid displaying an assumed loss, refund, or win while the result is unknown.

Use bounded retries for safe reads. Offer support after repeated failure. Do not trap the player in an automatic login or reload loop.

Cancel timers and close sockets on teardown. Prevent late replies from changing a replacement session's view.