Handling Errors

ZumoKit SDK uses comination of error types and error codes to provide information on errors occured.

Error Types

The type of error returned. In case of wallet errors, these errors can be safely displayed to the end users.

Error Type	Description
api_connection_error	Failure to connect to ZumoKit’s API.
api_error	Default error if something goes wrong on our side.
authentication_error	Failed to authenticate with ZumoKit's API.
wallet_error	Wallet errors are the most common type of error you should expect to handle. They result when user's wallet action can't be performed, e.g. balance too low or invalid wallet password are such errors.
invalid_argument_error	Errors triggered when failing to validate arguments, e.g. when a destination address is invalid.
invalid_request_error	Invalid request errors arise when request to API has invalid parameters.
rate_limit_error	Too many requests hit the API too quickly.

Error Codes

Below is a list of possible error codes that can be returned, along with additional information about how to resolve them.

Common Errors

• unknown_error

Unexpected error has occured. This error code is common to all error types.

Authentication Errors

• not_authorized

User's previous session has expired. User should login again.

• missing_authentication_token

Returned if action requires a user to be logged in but no valid authentication token is found in request. Make sure user authentication has been successful before creating a wallet or performing other actions which require active user.

• external_authentication_failed

Returned when authentication within Zumo environment failed. Make sure authentication was successful and retry authentication in case this error persists.

Wallet Errors

• wallet_limit_exceeded

Could not create wallet. Wallet already exists.

• no_wallet_to_recover_found

No wallet found to recover. Check if wallet exists.

• invalid_recovery_phrase

The provided recovery phrase does not correspond to existing wallet.

• invalid_password

Wallet could not be unlocked with provided password.

• signing_error

Something went wrong signing transaction.

• utxo_signing_error

Unspent transaction output could not be signed.

• invalid_transaction

Signed transaction is invalid. Make sure you are using correct chain id and that your wallet is unlocked.

• insufficient_funds

Returned when there are insufficient funds for desired transaction. Make sure gas * price + value <= balance.

• nonce_too_low

Returned when transactions nonce is too low. Increase nonce manually and try again or wait for account details to be updated.

• gas_too_low

Returned when gas price is too low while sending a transaction. Make sure gas price is 1 or greater.

• known_transaction

Returned when identical transaction is detected on local node. Very similar to nonce_too_low error, increase nonce manually or wait for account details to be updated.

• error_submitting_transaction

Generic error that is returned when something went wrong while trying to submit your transaction to blockchain.

Invalid Argument Errors

• invalid_mnemonic_word_count

Invalid length of mnemonic phrase. Mnemonic phrase should be 12, 15, 18, 21 or 24 words long.

• invalid_network_type

Account network type not supported.

• bitcoin_overflow

Bitcoin amount exceeds maximum 63 bit precision.

• invalid_hd_wallet_path

Transaction could not be signed. Private key derivation path is invalid.

• change_account_not_found

Selected change account does not exist.

• account_not_found

Selected account does not exist.

• invalid_transaction_value

Invalid transaction value.

• invalid_fee_rate

Invalid fee rate. Fee rate should be an integer value.

• invalid_address

Destination address is invalid.

• invalid_account_type

Account type not supported. Currently only Compatibility BTC and Standard ETH accounts are fully supported.

• nonce_overflow

Nonce too long. Maximum supported nonce size is 32 bytes.

• gas_overflow

Gas too low. Gas price and gas limit should be higher than 0.

• invalid_fee_rate

Gas too long. Cummulative gas limit and gas price should not exceed 30 bytes.

• no_destination_address

No destination address. In case no transaction data is provided destination address is obligatory.

• data_overflow

Transaction data overflow. Maximum data size supported by RLP encoding exceeds 16000000 bytes.

Invalid Request Errors

• entity_not_found

One or more entities we are trying to retrieve don't exist yet. Make sure your zumo app id and user token are correct.

• entity_already_exists

Entity we are trying to create already exists. Make sure entity with these parameters doesn't already exist.

• missing_required_parameter

One or more parameters are missing. Check our documentation for more details about the call you are trying to make.

Example

Android

iOS

React Native

try {
  // ZumoKit SDK methods either throw exceptions in synchronous calls or
  // return exceptions in callbacks, which you can throw
} catch (WalletException e) {
  // Wallet exception. Display the error to the user or
  // you can use error code to localize error message
  Log.i("zumokit/error-type", e.getErrorType());
  Log.i("zumokit/error-code", e.getErrorCode());
  Log.i("zumokit/error-messsage", e.getMessage());
} catch (InvalidArgumentException e) {
  // Some of the parameters failed to validate, you can
  // check error code and message for additional information
} catch (RateLimitException e) {
  // Too many requests made to the API too quickly
} catch (InvalidRequestException e) {
  // A request to ZumoKit's API failed, e.g. possible version mismatch
} catch (AuthenticationException e) {
  // Authentication with ZumoKit's API failed
} catch (APIException e) {
  // An unexepected server error has occured.
} catch (APIConnectionException e) {
  // Network communication with ZumoKit API failed
} catch (ZumoKitException e) {
  // Base class from which other ZumoKit exceptions derive,
  // you can display a very generic error to the user
} catch (Exception e) {
  // Something else happened, completely unrelated to ZumoKit
}

switch (error.code) {
  case ZKWalletError:
    // Wallet error. Display the error to the user or
    // you can use error code to localize error message
    NSLog(@"ZumoKit Error Type: %@", error.userInfo[ZKZumoKitErrorTypeKey]);
    NSLog(@"ZumoKit Error Code: %@", error.userInfo[ZKZumoKitErrorCodeKey]);
    NSLog(@"ZumoKit Error Message: %@", error.localizedDescription);
    break;
  case ZKInvalidArgumentError:
    // Some of the parameters failed to validate, you can
    // check error code and message for additional information
    break;
  case ZKRateLimitError:
    // Too many requests made to the API too quickly
    break;
  case ZKInvalidRequestError:
    // A request to ZumoKit's API failed, e.g. possible version mismatch
    break;
  case ZKAuthenticationError:
    // Authentication with ZumoKit's API failed
    break;
  case ZKAPIError:
    // An unexepected server error has occured.
    break;
  case ZKAPIConnectionError:
    // Network communication with ZumoKit API failed
    break;
  default:
    // Something else happened, completely unrelated to ZumoKit
    break;
}

switch (error.type) {
  case 'wallet_error':
    // Wallet error. Display the error to the user or
    // you can use error code to localize error message
    { type, code, message } = error;
    break;
  case 'invalid_argument_error':
    // Some of the parameters failed to validate, you can
    // check error code and message for additional information
    break;
  case 'rate_limit_error':
    // Too many requests made to the API too quickly
    break;
  case 'invalid_request_error':
    // A request to ZumoKit's API failed, e.g. possible version mismatch
    break;
  case 'authentication_error':
    // Authentication with ZumoKit's API failed
    break;
  case 'api_error':
    // An unexepected server error has occured.
    break;
  case 'api_connection_error':
    // Network communication with ZumoKit API failed
    break;
  default:
    // Something else happened, completely unrelated to ZumoKit
    break;
}