0
# @ledgerhq/errors
1

2
@ledgerhq/errors provides a comprehensive error handling system for Ledger hardware wallet applications and libraries. It includes a collection of custom error classes specifically designed for Ledger device communication, transport protocols, and blockchain interactions with utilities for creating custom error classes, serializing and deserializing errors for cross-context communication, and maintaining a unified error taxonomy across the Ledger ecosystem.
3

4
## Package Information
5

6
- **Package Name**: @ledgerhq/errors
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @ledgerhq/errors`
10

11
## Core Imports
12

13
```typescript
14
import { TransportError, TransportStatusError, StatusCodes } from "@ledgerhq/errors";
15
import { serializeError, deserializeError, createCustomErrorClass } from "@ledgerhq/errors";
16
import { 
17
  NoDBPathGiven, DBWrongPassword, DBNotReset,
18
  EthAppPleaseEnableContractData,
19
  UpdateFetchFileFail, UpdateIncorrectHash, UpdateIncorrectSig
20
} from "@ledgerhq/errors";
21
```
22

23
For CommonJS:
24

25
```javascript
26
const { TransportError, TransportStatusError, StatusCodes } = require("@ledgerhq/errors");
27
const { serializeError, deserializeError, createCustomErrorClass } = require("@ledgerhq/errors");
28
const { 
29
  NoDBPathGiven, DBWrongPassword, DBNotReset,
30
  EthAppPleaseEnableContractData,
31
  UpdateFetchFileFail, UpdateIncorrectHash, UpdateIncorrectSig
32
} = require("@ledgerhq/errors");
33
```
34

35
## Basic Usage
36

37
```typescript
38
import { 
39
  TransportError, 
40
  TransportStatusError, 
41
  StatusCodes,
42
  DeviceNotGenuineError,
43
  serializeError,
44
  deserializeError
45
} from "@ledgerhq/errors";
46

47
// Using specific error classes
48
try {
49
  // Device operation
50
} catch (error) {
51
  if (error instanceof DeviceNotGenuineError) {
52
    console.log("Device authenticity check failed");
53
  }
54
}
55

56
// Using transport errors
57
const transportError = new TransportError("Communication failed", "USB_DISCONNECT");
58

59
// Using transport status errors
60
const statusError = new TransportStatusError(StatusCodes.DEVICE_LOCKED);
61

62
// Error serialization for cross-context communication
63
const serialized = serializeError(error);
64
const restored = deserializeError(serialized);
65
```
66

67
## Architecture
68

69
@ledgerhq/errors is built around several key patterns:
70

71
- **Custom Error Factory**: `createCustomErrorClass` generates custom error types with consistent behavior
72
- **Transport Layer**: Specialized errors for device communication (`TransportError`, `TransportStatusError`)
73
- **Status Code Integration**: Direct mapping to Ledger device status codes for hardware-level error handling
74
- **Serialization System**: Cross-context error communication with `serializeError`/`deserializeError`
75
- **Error Taxonomy**: Organized categories covering device management, user interactions, blockchain operations, database operations, and application-specific scenarios
76

77
## Capabilities
78

79
### Error Utilities
80

81
Core utilities for creating custom error classes and handling error serialization across different contexts.
82

83
```typescript { .api }
84
function createCustomErrorClass(name: string): CustomErrorFunc;
85
function serializeError(value: any): undefined | To | string;
86
function deserializeError(object: any): Error;
87
function addCustomErrorDeserializer(
88
  name: string,
89
  deserializer: (obj: any) => any
90
): void;
91

92
type CustomErrorFunc = (
93
  message?: string,
94
  fields?: { [key: string]: any }
95
) => void;
96

97
interface To {
98
  name?: string;
99
  message?: string;
100
  stack?: string;
101
}
102
```
103

104
[Error Utilities](./error-utilities.md)
105

106
### Transport Errors
107

108
Specialized error classes for Ledger device communication, including transport-level failures and device status code errors.
109

110
```typescript { .api }
111
function TransportError(message: string, id: string): void;
112
function TransportStatusError(statusCode: number): void;
113

114
const StatusCodes: {
115
  PIN_REMAINING_ATTEMPTS: number;
116
  INCORRECT_LENGTH: number;
117
  SECURITY_STATUS_NOT_SATISFIED: number;
118
  CONDITIONS_OF_USE_NOT_SATISFIED: number;
119
  OK: number;
120
  // ... 25+ additional status codes
121
};
122

123
function getAltStatusMessage(code: number): string | undefined | null;
124
```
125

126
[Transport Errors](./transport-errors.md)
127

128
### Device Management Errors
129

130
Error classes for Ledger device management operations including device state validation, connection issues, and hardware-specific errors.
131

132
```typescript { .api }
133
const CantOpenDevice: CustomErrorFunc;
134
const DeviceNotGenuineError: CustomErrorFunc;
135
const DeviceOnDashboardExpected: CustomErrorFunc;
136
const DeviceOnDashboardUnexpected: CustomErrorFunc;
137
const DeviceInOSUExpected: CustomErrorFunc;
138
const DeviceHalted: CustomErrorFunc;
139
const DisconnectedDevice: CustomErrorFunc;
140
const DisconnectedDeviceDuringOperation: CustomErrorFunc;
141
// ... 15+ additional device management errors
142
```
143

144
[Device Management Errors](./device-management-errors.md)
145

146
### User Interaction Errors
147

148
Error classes for user interaction scenarios including user refusals, permission issues, and input validation failures.
149

150
```typescript { .api }
151
const UserRefusedOnDevice: CustomErrorFunc;
152
const UserRefusedAddress: CustomErrorFunc;
153
const UserRefusedFirmwareUpdate: CustomErrorFunc;
154
const UserRefusedAllowManager: CustomErrorFunc;
155
const UserRefusedDeviceNameChange: CustomErrorFunc;
156
const NoAccessToCamera: CustomErrorFunc;
157
const CantScanQRCode: CustomErrorFunc;
158
const PairingFailed: CustomErrorFunc;
159
// ... 5+ additional user interaction errors
160
```
161

162
[User Interaction Errors](./user-interaction-errors.md)
163

164
### Account and Balance Errors
165

166
Error classes for account management and balance validation including insufficient funds, account state issues, and transaction validation errors.
167

168
```typescript { .api }
169
const AccountNameRequiredError: CustomErrorFunc;
170
const AccountNotSupported: CustomErrorFunc;
171
const NotEnoughBalance: CustomErrorFunc;
172
const NotEnoughBalanceToDelegate: CustomErrorFunc;
173
const NotEnoughBalanceInParentAccount: CustomErrorFunc;
174
const NotEnoughSpendableBalance: CustomErrorFunc;
175
const NotEnoughBalanceBecauseDestinationNotCreated: CustomErrorFunc;
176
const WrongDeviceForAccount: CustomErrorFunc;
177
const NoAddressesFound: CustomErrorFunc;
178
// ... 5+ additional account and balance errors
179
```
180

181
[Account and Balance Errors](./account-balance-errors.md)
182

183
### Application and Manager Errors
184

185
Error classes for Ledger application management including app installation, dependencies, firmware updates, and manager operations.
186

187
```typescript { .api }
188
const ManagerAppAlreadyInstalledError: CustomErrorFunc;
189
const ManagerAppRelyOnBTCError: CustomErrorFunc;
190
const ManagerAppDepInstallRequired: CustomErrorFunc;
191
const ManagerAppDepUninstallRequired: CustomErrorFunc;
192
const ManagerDeviceLockedError: CustomErrorFunc;
193
const ManagerNotEnoughSpaceError: CustomErrorFunc;
194
const FirmwareNotRecognized: CustomErrorFunc;
195
const FirmwareOrAppUpdateRequired: CustomErrorFunc;
196
const UpdateYourApp: CustomErrorFunc;
197
// ... 10+ additional application and manager errors
198
```
199

200
[Application and Manager Errors](./application-manager-errors.md)
201

202
### Network and API Errors
203

204
Error classes for network connectivity, API communication, and external service integration issues.
205

206
```typescript { .api }
207
const NetworkDown: CustomErrorFunc;
208
const LedgerAPIError: CustomErrorFunc;
209
const LedgerAPIErrorWithMessage: CustomErrorFunc;
210
const LedgerAPINotAvailable: CustomErrorFunc;
211
const LedgerAPI4xx: CustomErrorFunc;
212
const LedgerAPI5xx: CustomErrorFunc;
213
const WebsocketConnectionError: CustomErrorFunc;
214
const WebsocketConnectionFailed: CustomErrorFunc;
215
// ... 5+ additional network and API errors
216
```
217

218
[Network and API Errors](./network-api-errors.md)
219

220
### Currency and Transaction Errors
221

222
Error classes for cryptocurrency operations including address validation, transaction processing, fee estimation, and currency-specific issues.
223

224
```typescript { .api }
225
const CurrencyNotSupported: CustomErrorFunc;
226
const InvalidAddress: CustomErrorFunc;
227
const InvalidAddressBecauseDestinationIsAlsoSource: CustomErrorFunc;
228
const InvalidXRPTag: CustomErrorFunc;
229
const AmountRequired: CustomErrorFunc;
230
const RecipientRequired: CustomErrorFunc;
231
const FeeEstimationFailed: CustomErrorFunc;
232
const FeeRequired: CustomErrorFunc;
233
const FeeTooHigh: CustomErrorFunc;
234
const NotEnoughGas: CustomErrorFunc;
235
const GasLessThanEstimate: CustomErrorFunc;
236
// ... 10+ additional currency and transaction errors
237
```
238

239
[Currency and Transaction Errors](./currency-transaction-errors.md)
240

241
### Database Errors
242

243
Error classes for database operations and configuration issues in Ledger applications.
244

245
```typescript { .api }
246
const NoDBPathGiven: CustomErrorFunc;
247
const DBWrongPassword: CustomErrorFunc;
248
const DBNotReset: CustomErrorFunc;
249
```
250

251
[Database Errors](./database-errors.md)