axios-axios/examples/improved-network-errors.md

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

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."
  });