0
# Network and API Errors
1

2
Error classes for network connectivity, API communication, and external service integration issues.
3

4
## Types
5

6
```typescript { .api }
7
interface APIConfig {
8
  baseURL: string;
9
  apiKey?: string;
10
  timeout?: number;
11
  headers?: Record<string, string>;
12
}
13
```
14

15
## Capabilities
16

17
### Network Connectivity Errors
18

19
Errors related to network connectivity and connection failures.
20

21
```typescript { .api }
22
const NetworkDown: CustomErrorFunc;
23
const WebsocketConnectionError: CustomErrorFunc;
24
const WebsocketConnectionFailed: CustomErrorFunc;
25
```
26

27
**Usage Examples:**
28

29
```typescript
30
import { 
31
  NetworkDown,
32
  WebsocketConnectionError,
33
  WebsocketConnectionFailed
34
} from "@ledgerhq/errors";
35

36
// Handle network connectivity issues
37
try {
38
  await fetchAccountData();
39
} catch (error) {
40
  if (error instanceof NetworkDown) {
41
    console.log("Network is unavailable - please check your connection");
42
    showOfflineMode();
43
  }
44
}
45

46
// Handle websocket connection errors
47
try {
48
  await connectWebSocket();
49
} catch (error) {
50
  if (error instanceof WebsocketConnectionError) {
51
    console.log("WebSocket connection error - retrying...");
52
    retryConnection();
53
  } else if (error instanceof WebsocketConnectionFailed) {
54
    console.log("WebSocket connection failed - falling back to HTTP");
55
    useHttpFallback();
56
  }
57
}
58

59
// Example with retry logic
60
async function establishWebSocketConnection(maxRetries: number = 3): Promise<WebSocket> {
61
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
62
    try {
63
      return await connectWebSocket();
64
    } catch (error) {
65
      if (error instanceof WebsocketConnectionFailed && attempt < maxRetries) {
66
        console.log(`WebSocket attempt ${attempt} failed, retrying...`);
67
        await delay(1000 * attempt); // Exponential backoff
68
        continue;
69
      }
70
      throw error;
71
    }
72
  }
73
  throw new WebsocketConnectionFailed("Max connection attempts exceeded");
74
}
75
```
76

77
### Ledger API Errors
78

79
Errors specific to Ledger's API services and backend communication.
80

81
```typescript { .api }
82
const LedgerAPIError: CustomErrorFunc;
83
const LedgerAPIErrorWithMessage: CustomErrorFunc;
84
const LedgerAPINotAvailable: CustomErrorFunc;
85
const LedgerAPI4xx: CustomErrorFunc;
86
const LedgerAPI5xx: CustomErrorFunc;
87
```
88

89
**Usage Examples:**
90

91
```typescript
92
import { 
93
  LedgerAPIError,
94
  LedgerAPIErrorWithMessage,
95
  LedgerAPINotAvailable,
96
  LedgerAPI4xx,
97
  LedgerAPI5xx
98
} from "@ledgerhq/errors";
99

100
// Handle general API errors
101
try {
102
  await callLedgerAPI("/accounts");
103
} catch (error) {
104
  if (error instanceof LedgerAPIError) {
105
    console.log("Ledger API request failed");
106
  }
107
}
108

109
// Handle API errors with specific messages
110
try {
111
  const response = await fetch("/api/transactions");
112
  if (!response.ok) {
113
    const errorData = await response.json();
114
    throw new LedgerAPIErrorWithMessage(errorData.message || "API request failed");
115
  }
116
} catch (error) {
117
  if (error instanceof LedgerAPIErrorWithMessage) {
118
    showUserMessage(error.message);
119
  }
120
}
121

122
// Handle API availability
123
async function checkAPIStatus() {
124
  try {
125
    await fetch("/api/health");
126
  } catch (error) {
127
    throw new LedgerAPINotAvailable("Ledger API services are currently unavailable");
128
  }
129
}
130

131
// Handle HTTP status code errors
132
async function handleAPIResponse(response: Response) {
133
  if (response.status >= 400 && response.status < 500) {
134
    throw new LedgerAPI4xx(`Client error: ${response.status} ${response.statusText}`);
135
  } else if (response.status >= 500) {
136
    throw new LedgerAPI5xx(`Server error: ${response.status} ${response.statusText}`);
137
  }
138
  return response;
139
}
140

141
// Example API client with comprehensive error handling
142
class LedgerAPIClient {
143
  async request(endpoint: string, options: RequestInit = {}) {
144
    try {
145
      const response = await fetch(`https://api.ledger.com${endpoint}`, options);
146
      
147
      if (response.status >= 500) {
148
        throw new LedgerAPI5xx(`Server error: ${response.status}`);
149
      } else if (response.status >= 400) {
150
        const errorData = await response.json().catch(() => ({}));
151
        throw new LedgerAPI4xx(errorData.message || `Client error: ${response.status}`);
152
      }
153
      
154
      return response.json();
155
    } catch (error) {
156
      if (error instanceof TypeError && error.message.includes("fetch")) {
157
        throw new LedgerAPINotAvailable("Unable to connect to Ledger API");
158
      }
159
      throw error;
160
    }
161
  }
162
  
163
  async getAccount(accountId: string) {
164
    try {
165
      return await this.request(`/accounts/${accountId}`);
166
    } catch (error) {
167
      if (error instanceof LedgerAPI4xx) {
168
        console.log("Account not found or access denied");
169
      } else if (error instanceof LedgerAPI5xx) {
170
        console.log("Server error - please try again later");
171
      }
172
      throw error;
173
    }
174
  }
175
}
176
```
177

178
### Endpoint Configuration Errors
179

180
Errors related to API endpoint configuration and connectivity.
181

182
```typescript { .api }
183
const EnpointConfigError: CustomErrorFunc;
184
```
185

186
**Usage Examples:**
187

188
```typescript
189
import { EnpointConfigError } from "@ledgerhq/errors";
190

191
// Validate endpoint configuration
192
function validateEndpointConfig(config: APIConfig) {
193
  if (!config.baseURL || !config.apiKey) {
194
    throw new EnpointConfigError("API endpoint configuration is incomplete");
195
  }
196
  
197
  try {
198
    new URL(config.baseURL);
199
  } catch {
200
    throw new EnpointConfigError("Invalid API endpoint URL format");
201
  }
202
}
203

204
// Handle configuration errors in API client
205
class APIClient {
206
  constructor(config: APIConfig) {
207
    try {
208
      validateEndpointConfig(config);
209
      this.config = config;
210
    } catch (error) {
211
      if (error instanceof EnpointConfigError) {
212
        console.error("API client initialization failed:", error.message);
213
      }
214
      throw error;
215
    }
216
  }
217
  
218
  async makeRequest(path: string) {
219
    if (!this.config.baseURL) {
220
      throw new EnpointConfigError("API endpoint not configured");
221
    }
222
    
223
    // Make request...
224
  }
225
}
226

227
// Example usage
228
try {
229
  const client = new APIClient({
230
    baseURL: process.env.API_URL,
231
    apiKey: process.env.API_KEY
232
  });
233
} catch (error) {
234
  if (error instanceof EnpointConfigError) {
235
    console.log("Please check your API configuration");
236
  }
237
}
238
```