How Axios Handles Network Disconnects and Offline States

This article explores how the Axios HTTP client behaves when a network disconnect occurs or when a device transitions to an offline state. You will learn about the specific error structures Axios generates during network failures, how to detect offline states using error codes and request interceptors, and how to implement automated retry and offline request queuing strategies to maintain application stability.

The Default Axios Behavior on Network Failure

When a network disconnect occurs while a request is in transit, or if a request is initiated while the client is entirely offline, the underlying network call fails at the socket or transport layer. Axios handles this by immediately rejecting the request promise and returning an AxiosError object.

Unlike standard HTTP error responses (such as 404 or 500 status codes) where the server responds with headers and a body, a network disconnect means no HTTP response was ever received. Consequently, the returned error object will have error.response set to undefined, while error.request will contain the instance of the request (such as an XMLHttpRequest in browsers or a ClientRequest in Node.js).

Identifying Network Disconnect Errors

To distinguish between a regular server error and a network disconnection in your code, you can inspect the properties on the caught error object.

In modern versions of Axios (v1.x and later), a standard network drop or inability to reach the host produces a standardized error code:

axios.get('https://api.example.com/data')
  .then(response => {
    console.log(response.data);
  })
  .catch(error => {
    if (axios.isAxiosError(error)) {
      if (error.code === 'ERR_NETWORK') {
        console.error('Network disconnect or device is offline.');
      } else if (error.code === 'ECONNABORTED') {
        console.error('The request timed out due to poor connectivity.');
      } else if (error.response) {
        console.error(`Server responded with status: ${error.response.status}`);
      }
    }
  });

• ERR_NETWORK: Indicates that the request could not be completed due to a network-level failure, such as losing Wi-Fi, cellular data drops, or DNS resolution failures.
• ECONNABORTED: Occurs when a request exceeds the configured timeout threshold due to a slow or hanging connection.

Preventing Requests While Offline

By default, Axios attempts to send requests regardless of whether the operating system or browser reports an active internet connection. To avoid making unnecessary calls that are guaranteed to fail, you can combine Axios request interceptors with platform-native connectivity checks.

In browser environments, you can check navigator.onLine:

axios.interceptors.request.use((config) => {
  if (typeof navigator !== 'undefined' && !navigator.onLine) {
    return Promise.reject(new axios.AxiosError(
      'Device is currently offline',
      'ERR_NETWORK',
      config
    ));
  }
  return config;
}, (error) => {
  return Promise.reject(error);
});

Handling Disconnects with Automated Retries

Because network drops are often transient, a common pattern is to implement automated retry logic. Axios response interceptors can intercept ERR_NETWORK errors and retry the request using an exponential backoff strategy:

axios.interceptors.response.use(null, async (error) => {
  const { config } = error;

  // Initialize retry configuration
  config.retryCount = config.retryCount || 0;
  const maxRetries = 3;

  // Only retry on network errors or timeouts
  const shouldRetry = error.code === 'ERR_NETWORK' || error.code === 'ECONNABORTED';

  if (shouldRetry && config.retryCount < maxRetries) {
    config.retryCount += 1;
    
    // Exponential backoff delay: 1s, 2s, 4s...
    const delay = Math.pow(2, config.retryCount - 1) * 1000;
    await new Promise((resolve) => setTimeout(resolve, delay));
    
    return axios(config);
  }

  return Promise.reject(error);
});

Offline Request Queuing and Synchronization

For applications requiring offline support, intercepting failed requests allows you to store them in a queue (such as in localStorage or IndexedDB). Once the device detects that the connection has been restored via the browser online event or mobile network listeners, the queued Axios request configurations can be iterated through and re-dispatched sequentially.