0
# Transport Errors
1

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

4
## Capabilities
5

6
### Transport Error
7

8
Generic transport error for device communication failures, such as incorrect data received or communication breakdowns.
9

10
```typescript { .api }
11
/**
12
 * TransportError is used for any generic transport errors.
13
 * e.g. Error thrown when data received by exchanges are incorrect or if exchanged failed to communicate with the device for various reason.
14
 * @param message - Error message describing the transport failure
15
 * @param id - Identifier for the specific transport error
16
 */
17
function TransportError(message: string, id: string): void;
18
```
19

20
**Usage Examples:**
21

22
```typescript
23
import { TransportError } from "@ledgerhq/errors";
24

25
// Create transport error with specific ID
26
const usbError = new TransportError("USB device disconnected", "USB_DISCONNECT");
27
console.log(usbError.message); // "USB device disconnected"
28
console.log(usbError.id); // "USB_DISCONNECT"
29
console.log(usbError.name); // "TransportError"
30

31
// Handle in try-catch
32
try {
33
  // Device communication operation
34
} catch (error) {
35
  if (error instanceof TransportError) {
36
    console.log(`Transport failed: ${error.message} (${error.id})`);
37
  }
38
}
39
```
40

41
### Transport Status Error
42

43
Error thrown when a Ledger device returns a non-success status code, with automatic status code mapping and human-readable messages.
44

45
```typescript { .api }
46
/**
47
 * Error thrown when a device returned a non success status.
48
 * the error.statusCode is one of the `StatusCodes` exported by this library.
49
 * @param statusCode - The numeric status code returned by the device
50
 */
51
function TransportStatusError(statusCode: number): void;
52
```
53

54
**Usage Examples:**
55

56
```typescript
57
import { TransportStatusError, StatusCodes } from "@ledgerhq/errors";
58

59
// Create status error
60
const pinError = new TransportStatusError(StatusCodes.PIN_REMAINING_ATTEMPTS);
61
console.log(pinError.statusCode); // 0x63c0
62
console.log(pinError.statusText); // "PIN_REMAINING_ATTEMPTS"
63
console.log(pinError.message); // "Ledger device: PIN_REMAINING_ATTEMPTS (0x63c0)"
64

65
// Create error with unknown status code
66
const unknownError = new TransportStatusError(0x1234);
67
console.log(unknownError.statusText); // "UNKNOWN_ERROR"
68
console.log(unknownError.message); // "Ledger device: UNKNOWN_ERROR (0x1234)"
69

70
// Handle device errors
71
try {
72
  // Device operation
73
} catch (error) {
74
  if (error instanceof TransportStatusError) {
75
    if (error.statusCode === StatusCodes.CONDITIONS_OF_USE_NOT_SATISFIED) {
76
      console.log("User denied the operation");
77
    } else if (error.statusCode === StatusCodes.SECURITY_STATUS_NOT_SATISFIED) {
78
      console.log("Device is locked or access rights invalid");
79
    }
80
  }
81
}
82
```
83

84
### Status Codes
85

86
Comprehensive mapping of Ledger device status codes to numeric values for hardware-level error handling.
87

88
```typescript { .api }
89
const StatusCodes: {
90
  PIN_REMAINING_ATTEMPTS: 0x63c0;
91
  INCORRECT_LENGTH: 0x6700;
92
  MISSING_CRITICAL_PARAMETER: 0x6800;
93
  COMMAND_INCOMPATIBLE_FILE_STRUCTURE: 0x6981;
94
  SECURITY_STATUS_NOT_SATISFIED: 0x6982;
95
  CONDITIONS_OF_USE_NOT_SATISFIED: 0x6985;
96
  INCORRECT_DATA: 0x6a80;
97
  NOT_ENOUGH_MEMORY_SPACE: 0x6a84;
98
  REFERENCED_DATA_NOT_FOUND: 0x6a88;
99
  FILE_ALREADY_EXISTS: 0x6a89;
100
  INCORRECT_P1_P2: 0x6b00;
101
  INS_NOT_SUPPORTED: 0x6d00;
102
  CLA_NOT_SUPPORTED: 0x6e00;
103
  TECHNICAL_PROBLEM: 0x6f00;
104
  OK: 0x9000;
105
  MEMORY_PROBLEM: 0x9240;
106
  NO_EF_SELECTED: 0x9400;
107
  INVALID_OFFSET: 0x9402;
108
  FILE_NOT_FOUND: 0x9404;
109
  INCONSISTENT_FILE: 0x9408;
110
  ALGORITHM_NOT_SUPPORTED: 0x9484;
111
  INVALID_KCV: 0x9485;
112
  CODE_NOT_INITIALIZED: 0x9802;
113
  ACCESS_CONDITION_NOT_FULFILLED: 0x9804;
114
  CONTRADICTION_SECRET_CODE_STATUS: 0x9808;
115
  CONTRADICTION_INVALIDATION: 0x9810;
116
  CODE_BLOCKED: 0x9840;
117
  MAX_VALUE_REACHED: 0x9850;
118
  GP_AUTH_FAILED: 0x6300;
119
  LICENSING: 0x6f42;
120
  HALTED: 0x6faa;
121
};
122
```
123

124
**Usage Examples:**
125

126
```typescript
127
import { StatusCodes, TransportStatusError } from "@ledgerhq/errors";
128

129
// Check specific status codes
130
if (statusCode === StatusCodes.OK) {
131
  console.log("Operation successful");
132
} else if (statusCode === StatusCodes.CONDITIONS_OF_USE_NOT_SATISFIED) {
133
  throw new TransportStatusError(statusCode);
134
}
135

136
// Use in switch statement
137
switch (statusCode) {
138
  case StatusCodes.SECURITY_STATUS_NOT_SATISFIED:
139
    return "Device locked or invalid access rights";
140
  case StatusCodes.CONDITIONS_OF_USE_NOT_SATISFIED:
141
    return "Operation denied by user";
142
  case StatusCodes.INCORRECT_DATA:
143
    return "Invalid data received";
144
  default:
145
    return "Unknown device error";
146
}
147

148
// Convert to hex for logging
149
console.log(`Status: 0x${StatusCodes.PIN_REMAINING_ATTEMPTS.toString(16)}`);
150
// "Status: 0x63c0"
151
```
152

153
### Get Alternative Status Message
154

155
Returns human-readable error messages for common Ledger device status codes.
156

157
```typescript { .api }
158
/**
159
 * Returns human-readable message for status codes
160
 * @param code - The numeric status code
161
 * @returns Human-readable message or undefined/null if no mapping exists
162
 */
163
function getAltStatusMessage(code: number): string | undefined | null;
164
```
165

166
**Usage Examples:**
167

168
```typescript
169
import { getAltStatusMessage, StatusCodes } from "@ledgerhq/errors";
170

171
// Get human-readable messages
172
console.log(getAltStatusMessage(StatusCodes.INCORRECT_LENGTH));
173
// "Incorrect length"
174

175
console.log(getAltStatusMessage(StatusCodes.SECURITY_STATUS_NOT_SATISFIED));
176
// "Security not satisfied (dongle locked or have invalid access rights)"
177

178
console.log(getAltStatusMessage(StatusCodes.CONDITIONS_OF_USE_NOT_SATISFIED));
179
// "Condition of use not satisfied (denied by the user?)"
180

181
console.log(getAltStatusMessage(StatusCodes.INVALID_DATA));
182
// "Invalid data received"
183

184
// Handle technical problems (0x6f00-0x6fff range)
185
console.log(getAltStatusMessage(0x6f50));
186
// "Internal error, please report"
187

188
// Unknown status codes return undefined
189
console.log(getAltStatusMessage(0x1234)); // undefined
190

191
// Use in error handling
192
function handleStatusCode(code: number): string {
193
  const altMessage = getAltStatusMessage(code);
194
  if (altMessage) {
195
    return altMessage;
196
  }
197
  
198
  const statusText = Object.keys(StatusCodes)
199
    .find(k => StatusCodes[k] === code) || "UNKNOWN_ERROR";
200
  return statusText;
201
}
202
```
203

204
### Transport Interface Errors
205

206
Additional transport-related error classes for specific transport layer issues.
207

208
```typescript { .api }
209
const TransportOpenUserCancelled: CustomErrorFunc;
210
const TransportInterfaceNotAvailable: CustomErrorFunc;
211
const TransportRaceCondition: CustomErrorFunc;
212
const TransportWebUSBGestureRequired: CustomErrorFunc;
213
const BluetoothRequired: CustomErrorFunc;
214
```
215

216
**Usage Examples:**
217

218
```typescript
219
import { 
220
  TransportOpenUserCancelled,
221
  TransportInterfaceNotAvailable,
222
  TransportWebUSBGestureRequired,
223
  BluetoothRequired
224
} from "@ledgerhq/errors";
225

226
// Handle user cancellation
227
try {
228
  // Transport opening operation
229
} catch (error) {
230
  if (error instanceof TransportOpenUserCancelled) {
231
    console.log("User cancelled device connection");
232
  }
233
}
234

235
// Check for interface availability
236
if (!isTransportAvailable) {
237
  throw new TransportInterfaceNotAvailable("USB transport not available");
238
}
239

240
// WebUSB gesture requirement
241
throw new TransportWebUSBGestureRequired("User interaction required for WebUSB access");
242

243
// Bluetooth requirement
244
throw new BluetoothRequired("Bluetooth must be enabled for device connection");
245
```