hizi docs

Appearance

Error Handling ​

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

Response Types ​

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

// Error
{
  success: false;
  error: {
    code: string;          // stringified API_RETURNCODES value or engine-specific id
    message: string;
    passThroughData?: unknown;
  };
}

Checking for Errors ​

Always check success before accessing the result:

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

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. This list contains the errors that you can retry:

typescript
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 ​

CodeMeaning
BALANCETOOLOWThe player's balance is too low.
BETLIMITREACHEDThe bet exceeds the configured limit.
NETWORKERRORA problem occurred with the network connection.
RATELIMITEXCEEDEDThe client sent too many requests.
GENERICBETERRORAn unspecified error occurred with the bet.
RNGFAILUREThe RNG (random number generator) failed.
OPERATIONBEINGPROCESSEDThe system is still processing a previous operation.

Session Refresh ​

Refresh the session token when you get an authentication error or need to reload the game:

typescript
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 original login() response provides the refreshURL.

Example Error Handler ​

typescript
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 you access the response data.
  2. Show messages that players can understand. Error messages from the API may be localized.
  3. Distinguish between error types. Show a different UI for recoverable errors and fatal errors.
  4. Provide retry options. For recoverable errors, let the player try again.
  5. Maintain the game state. Do not crash or lose the UI state when an error occurs.
  6. Log technical details. Keep error codes in console logs for debugging.

Next Steps ​