From 08db960d9f1003b3c561026f636df2d6d5d8ca57 Mon Sep 17 00:00:00 2001
From: Samyak Dandge <141911040+Samy-in@users.noreply.github.com>
Date: Thu, 23 Oct 2025 18:50:22 +0530
Subject: [PATCH] docs: added example for improved network error handling (with
 Wrapper/Middleware approach) (#7171)

* Added enhanced network error handling with wrapper approach

This file enhances error handling for network issues in Axios requests, providing detailed messages for various error scenarios.

* Added documentation for my approach to network errors

This document explains how to enhance Axios network error messages to be more descriptive and human-readable. It details the wrapper function and provides examples of usage.

* Update examples/improved-network-errors.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* fix: md

---------

Co-authored-by: Jay <jasonsaayman@gmail.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---
 examples/improved-network-errors.md | 57 +++++++++++++++++++++
 examples/network_enhanced.js        | 77 +++++++++++++++++++++++++++++
 2 files changed, 134 insertions(+)
 create mode 100644 examples/improved-network-errors.md
 create mode 100644 examples/network_enhanced.js

diff --git a/examples/improved-network-errors.md b/examples/improved-network-errors.md
new file mode 100644
index 0000000..508c46c
--- /dev/null
+++ b/examples/improved-network-errors.md
@@ -0,0 +1,57 @@
+# Overview of this document:
+
+This document explains a simple approach to make Axios network errors more helpful and human-readable.  
+By default, Axios shows a generic `"Network Error"` message for many failures.  
+This can be confusing because it doesn't explain "what actually went wrong" (e.g., no internet, a timeout, a CORS issue, etc.).  
+
+Our approach adds clear, categorised error messages for different network issues.
+
+---
+
+==> Problem
+Axios currently throws the same `Network Error` message for many different cases:
+- The Internet is disconnected  
+- DNS lookup fails  
+- Server is down or refusing connections  
+- CORS blocked requests  
+- Request timed out  
+
+These cases all look the same to developers and users, making debugging harder.
+
+
+--> Our Approach — Wrapper / Middleware
+
+We created a small wrapper function called `enhanceNetworkError()` that:
+- Detects  Common network problems using `error.code`, `error.message`, and response status.
+- Adds a new field `error.detailedMessage` with a short, clear explanation.
+- Assigns a new `error.code` (like `ERR_TIMEOUT`, `ERR_DNS_FAILURE`, etc.).
+- Works for both browser and Node.js environments.
+
+The wrapper is used inside an Axios instance via a Response interceptor.
+
+-> How It Works
+
+1. When Axios throws an error, the interceptor catches it.  
+2. The `enhanceNetworkError()` function checks what type of error it is:
+   - Offline → `ERR_NO_INTERNET`
+   - DNS failure → `ERR_DNS_FAILURE`
+   - Timeout → `ERR_TIMEOUT`
+   - CORS blocked → `ERR_CORS_BLOCKED`
+   - Server-side → `ERR_SERVER`
+   - Client-side → `ERR_CLIENT`
+   - Other → `ERR_NETWORK_GENERIC`
+3. It returns a more descriptive error with both `code` and `detailedMessage`.
+
+
+-> Example Usage
+
+```javascript
+const api = createEnhancedClient({ baseURL: 'https://example.com' });
+
+api.get('/data')
+  .then(res => console.log(res.data))
+  .catch(err => {
+    console.error(err.code);            // e.g., ERR_TIMEOUT
+    console.error(err.detailedMessage); // e.g., "The request took too long to respond."
+  });
+```
diff --git a/examples/network_enhanced.js b/examples/network_enhanced.js
new file mode 100644
index 0000000..72f722d
--- /dev/null
+++ b/examples/network_enhanced.js
@@ -0,0 +1,77 @@
+import axios from 'axios';
+
+function enhanceNetworkError(error) {
+  // when Offline (no internet)
+  if (typeof navigator !== 'undefined' && !navigator.onLine) {
+    error.code = 'ERR_NO_INTERNET';
+    error.detailedMessage =
+      'No internet connection detected. Please check your connection and try again.';
+  }
+
+  // when DNS failure occurs (invalid domain)
+  else if (error.code === 'ENOTFOUND' || /dns/i.test(error.message)) {
+    error.code = 'ERR_DNS_FAILURE';
+    error.detailedMessage =
+      'Unable to reach the requested domain. Please verify the URL or your network settings.';
+  }
+
+  // when Connection refused by server
+  else if (error.code === 'ECONNREFUSED' || /refused/i.test(error.message)) {
+    error.code = 'ERR_CONNECTION_REFUSED';
+    error.detailedMessage =
+      'Connection was refused by the server. It may be temporarily unavailable.';
+  }
+
+  // when Request timeout happens
+  else if (error.code === 'ETIMEDOUT' || /timeout/i.test(error.message)) {
+    error.code = 'ERR_TIMEOUT';
+    error.detailedMessage =
+      'The request took too long to respond. Please try again later.';
+  }
+
+  // when CORS restriction happens (for browser only)
+  else if (/CORS/i.test(error.message)) {
+    error.code = 'ERR_CORS_BLOCKED';
+    error.detailedMessage =
+      'The request was blocked due to cross-origin restrictions.';
+  }
+
+  // when Server-side error occurs 
+  else if (error.response && error.response.status >= 500) {
+    error.code = 'ERR_SERVER';
+    error.detailedMessage =
+      'A server-side issue occurred. Please try again later.';
+  }
+
+  // when Client-side error occurs
+  else if (error.response && error.response.status >= 400) {
+    error.code = 'ERR_CLIENT';
+    error.detailedMessage =
+      'A client-side error occurred. Please check your request.';
+  }
+
+  //  when unknown network issue occurs
+  else {
+    error.code = 'ERR_NETWORK_GENERIC';
+    error.detailedMessage =
+      'A network issue occurred. Please check your connection or try again later.';
+  }
+
+  return error;
+}
+
+
+export function createEnhancedClient(config = {}) {
+  const client = axios.create(config);
+
+  client.interceptors.response.use(
+    response => response,
+    error => {
+      throw enhanceNetworkError(error);
+    }
+  );
+
+  return client;
+}
+
+export default enhanceNetworkError;