Error Handling

All network functions in @hizi.io/engine-sdk return a TNetworkResponse<T> - either a success or an error.

Response Types

// Success
{
  success: true;
  result: T;
}

// Error
{
  success: false;
  error: {
    code: API_RETURNCODES;
    message: string;
    passThroughData?: unknown;
  };
}

Checking for Errors

Always check success before accessing the result:

const response = await placeBet({
  backendURL,
  token: sessionToken,
  stake: stakeAmount,
});

if (!response.success) {
  console.error(`Error ${response.error.code}: ${response.error.message}`);
  return;
}

// Safe to access response.result
const gameResult = response.result.result;

Recoverable Errors

The package exports recoverableErrorCodes for errors that can be retried:

import { recoverableErrorCodes, API_RETURNCODES } from '@hizi.io/engine-sdk';

if (!response.success) {
  if (recoverableErrorCodes.includes(response.error.code)) {
    // Can retry - show "try again" to the player
    showRetryDialog(response.error.message);
  } else {
    // Fatal - may need to refresh the game
    showFatalError(response.error.message);
  }
}

Common Recoverable Error Codes

Code	Meaning
BALANCETOOLOW	Player has insufficient balance
BETLIMITREACHED	Bet exceeds configured limits
NETWORKERROR	Network connection issue
RATELIMITEXCEEDED	Too many requests
GENERICBETERROR	Generic betting error
RNGFAILURE	RNG system failure
OPERATIONBEINGPROCESSED	A previous operation is still being processed

Session Refresh

If you receive authentication errors or you need to reload the game, refresh the session token:

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

const refreshResponse = await refresh(refreshURL);
if (refreshResponse.success) {
  sessionToken = refreshResponse.result.token;
} else {
  // Refresh failed - redirect to login
  window.location.reload();
}

The refreshURL is provided in the original login() response.

Example Error Handler

import { TNetworkResponse, IErrorResponse, recoverableErrorCodes } from '@hizi.io/engine-sdk';

function handleError(error: IErrorResponse): void {
  console.error(`Game error ${error.code}:`, error.message);

  if (recoverableErrorCodes.includes(error.code)) {
    showErrorDialog({
      title: 'Unable to complete action',
      message: error.message || 'Please try again',
      buttons: ['Retry', 'Cancel'],
    });
  } else {
    showErrorDialog({
      title: 'Game Error',
      message: error.message || 'Please refresh the game',
      buttons: ['Refresh'],
    });
  }
}

Best Practices

1. Always check success before accessing response data
2. Show user-friendly messages - error messages from the API may be localized
3. Distinguish error types - show different UI for recoverable vs fatal errors
4. Provide retry options - for recoverable errors, let the player try again
5. Maintain game state - don't crash or lose UI state on errors
6. Log technical details - keep error codes in console logs for debugging

Next Steps

• Game Flow - Full game lifecycle implementation.
• Types & Interfaces - TNetworkResponse, IErrorResponse, and related types.