Axios 504 Gateway Timeout vs Client Timeout

This article explains how the Axios HTTP client handles HTTP 504 Gateway Timeout errors compared to client-side timeouts. While both scenarios indicate that an operation took too long to complete, they originate from different points in the network architecture and present distinct error structures within Axios. Understanding these differences is essential for debugging, writing accurate error handlers, and implementing effective retry strategies.

HTTP 504 Gateway Timeout in Axios

An HTTP 504 Gateway Timeout is a standard server-side HTTP status code. It occurs when a server acting as a gateway or proxy (such as Nginx, Cloudflare, or an API gateway) does not receive a timely response from an upstream backend server to complete the request.

Because a 504 error is a valid HTTP response delivered back to the client over the network, Axios handles it as a rejected promise with a fully populated response object.

When inspecting the error in Axios:

• error.response is defined.
• error.response.status is equal to 504.
• error.response.data contains whatever error payload the gateway or proxy returned (often HTML or a JSON error message).
• error.request contains the completed HTTP request object.

Client-Side Timeout in Axios

A client-side timeout occurs entirely on the client environment running Axios (such as Node.js or the browser). It is controlled by the timeout configuration property passed to an Axios instance or request (e.g., { timeout: 5000 }).

If the local timer expires before Axios receives any response headers from the server, Axios aborts the request locally and rejects the promise.

When inspecting a client-side timeout in Axios:

• error.response is undefined because no response was ever received over the wire.
• error.code is typically set to 'ECONNABORTED' or 'ETIMEDOUT'.
• error.message usually matches a string such as timeout of 5000ms exceeded.
• error.request is defined because the request was created and sent.

Key Differences Summary

Handling Both Errors in Code

To properly handle and differentiate these two timeout conditions in an Axios catch block or interceptor, evaluate both error.code and error.response:

axios.get('https://api.example.com/data', { timeout: 5000 })
  .then(response => {
    console.log('Success:', response.data);
  })
  .catch(error => {
    if (error.code === 'ECONNABORTED') {
      // Client-side timeout
      console.error('Client timeout: The request took longer than 5000ms to complete.');
    } else if (error.response && error.response.status === 504) {
      // Server-side gateway timeout
      console.error('Gateway timeout (504): The proxy failed to get a response from the upstream server.');
    } else if (error.response) {
      // Other HTTP server errors (e.g., 500, 404, 403)
      console.error(`HTTP Error: ${error.response.status}`);
    } else {
      // Network failures or setup issues
      console.error('Network Error:', error.message);
    }
  });

Recognizing this distinction ensures you apply the correct mitigation: optimizing upstream server performance and proxy settings for 504 errors, versus adjusting client timeout thresholds or handling user connectivity for client-side timeouts.