Wrap network errors in ApiError for consistent error handling

[TaprootFreak]

Summary

Wrap native fetch errors in ApiError objects for consistent error handling across the application.

Problem

When the API server is unreachable (e.g., wrong URL, server down, CORS issues), fetch() throws a native TypeError: Failed to fetch. This breaks the error handling pattern used throughout the codebase, which expects ApiError objects with statusCode and message properties.

Solution

1. Catch network errors from fetch() and wrap them in ApiError:

   • statusCode: 0 indicates network-level failure (distinct from HTTP status codes ≥100)
   • message: "Network error: {original message}" preserves the original error for debugging

2. Add JSDoc documentation to ApiError.statusCode explaining that 0 means network error

// api.hook.ts
.catch((error: unknown) => {
  const message = error instanceof Error ? error.message : String(error);
  throw {
    statusCode: 0,
    message: `Network error: ${message}`,
  } as ApiError;
})

// error.ts
export interface ApiError {
  /**
   * HTTP status code from the API response.
   * A value of 0 indicates a network-level error (e.g., server unreachable, CORS, timeout).
   */
  statusCode: number;
  message: string;
}

Breaking Change

Before	After
TypeError with message: "Failed to fetch"	ApiError with statusCode: 0, message: "Network error: Failed to fetch"

Code using error instanceof TypeError will need adjustment. Analysis of services repo shows no such patterns.

Files Changed

• packages/react/src/hooks/api.hook.ts - wrap fetch errors
• packages/react/src/definitions/error.ts - document statusCode: 0

Test Plan

• Set REACT_APP_API_URL to unreachable endpoint (e.g., http://localhost:9999)
• Verify error shows Network error: Failed to fetch
• Verify error.statusCode === 0
• Verify existing error handling in consuming apps works