> ## Documentation Index
> Fetch the complete documentation index at: https://bkey.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Error handling

> BmoniSignerException codes and how to handle them.

All SDK failures surface as a `BmoniSignerException` carrying:

* `errorCode` — a `BmoniSignerErrorCode` enum value for programmatic branching
* `message` — a human-readable description

```dart theme={null}
try {
  await BmoniEmbeddedSdk.initWallet();
} on BmoniSignerException catch (e) {
  print('Code: ${e.errorCode}');   // BmoniSignerErrorCode.walletAlreadyExists
  print('Message: ${e.message}');  // "A wallet already exists on this device."
}
```

***

## Error codes

### Signing errors (`0x3001xxxx`)

Originate inside the native BMONISigner SDK.

| Constant                | Hex          | When it is thrown                                                   |
| ----------------------- | ------------ | ------------------------------------------------------------------- |
| `walletAlreadyExists`   | `0x30010010` | `initWallet` called while a wallet is already stored on disk.       |
| `signInvalidMessage`    | `0x30010001` | The supplied message could not be processed.                        |
| `signInvalidPrivateKey` | `0x30010002` | The stored key could not be recovered or decrypted.                 |
| `signInvalidHash`       | `0x30010003` | The hash argument was not a valid `0x`-prefixed 32-byte hex string. |
| `signProcess`           | `0x30010004` | Generic ECDSA signing failure.                                      |
| `signKeygen`            | `0x30010005` | secp256k1 keypair generation failed.                                |
| `signEip55`             | `0x30010006` | EIP-55 checksum derivation failed.                                  |

### PIN errors (`0x4xxxxxxx`)

Generated by the Dart-layer PIN gate.

| Constant        | Hex          | When it is thrown                                                     |
| --------------- | ------------ | --------------------------------------------------------------------- |
| `pinNotSet`     | `0x40000001` | A PIN-gated call was attempted but no PIN has been set.               |
| `pinAlreadySet` | `0x40000002` | `setPin` called while a PIN already exists — use `changePin` instead. |
| `pinMismatch`   | `0x40000003` | The supplied PIN did not match the stored digest.                     |
| `pinInvalid`    | `0x40000004` | The supplied PIN was empty, the wrong length, or otherwise invalid.   |

### Bridge errors (`0x5xxxxxxx`)

Generated by the Dart method-channel bridge.

| Constant               | Hex          | When it is thrown                                                                                |
| ---------------------- | ------------ | ------------------------------------------------------------------------------------------------ |
| `unexpectedNativeNull` | `0x50000001` | A native method that promised a non-null result returned `null` — indicates a plugin-bridge bug. |

***

## Handling the most common cases

```dart theme={null}
Future<void> handleSigningFlow() async {
  try {
    final String sig = await BmoniEmbeddedSdk.signMessage(
      'Hello',
      pin: userEnteredPin,
    );
    onSuccess(sig);
  } on BmoniSignerException catch (e) {
    switch (e.errorCode) {
      case BmoniSignerErrorCode.pinNotSet:
        // Redirect the user to the PIN setup flow.
        break;
      case BmoniSignerErrorCode.pinMismatch:
        // Ask the user to re-enter their PIN.
        break;
      case BmoniSignerErrorCode.pinInvalid:
        // PIN was the wrong length or empty.
        break;
      case BmoniSignerErrorCode.walletAlreadyExists:
        // Only thrown by initWallet — show a re-provision dialog.
        break;
      default:
        // Native or bridge error — log and show a generic message.
        debugPrint('Unexpected SDK error: ${e.message} (${e.errorCode})');
    }
  }
}
```

***

## PlatformException

In rare cases the method channel itself may throw a Flutter `PlatformException`. These are distinct from `BmoniSignerException` and typically indicate a misconfigured platform environment:

```dart theme={null}
import 'package:flutter/services.dart';

try {
  await BmoniEmbeddedSdk.initWallet();
} on BmoniSignerException catch (e) {
  // SDK-level error
} on PlatformException catch (e) {
  debugPrint('Platform error: ${e.message ?? e.code}');
}
```