Understanding the Axios Error Object Structure

When an HTTP request fails in the Axios library, it rejects the promise and returns an AxiosError object containing detailed diagnostic information about the failure. Understanding the structure of this error object is essential for effective error handling, debugging, and providing meaningful feedback to users. This article outlines the primary properties of the Axios error object, breaks down the nested response payload, and explains how to inspect errors across different failure scenarios.

The Top-Level AxiosError Object

An AxiosError extends the standard JavaScript Error object and includes several key properties:

  • message (string): A human-readable description of the error (for example, "Request failed with status code 404").
  • name (string): The name of the error, typically "AxiosError".
  • code (string | undefined): An error code string indicating the nature of the error, such as "ERR_BAD_REQUEST", "ERR_NETWORK", or "ECONNABORTED".
  • config (object): The full Axios configuration object used to generate the request (contains URL, method, headers, timeout settings, etc.).
  • request (object | undefined): The underlying native request object. In browser environments, this is an XMLHttpRequest instance; in Node.js environments, it is an http.ClientRequest instance.
  • response (object | undefined): The response object returned by the server if the request reached the server and the server replied with a status code outside the 2xx range.
  • isAxiosError (boolean): A boolean flag set to true to easily verify that the error originated from Axios.
  • toJSON() (function): A helper method that returns a serializable JSON object containing the error's key properties.

The error.response Structure

When a request is successfully received by the server but results in an HTTP 4xx or 5xx status code, Axios populates the error.response property with the following structure:

  • response.data: The payload or message body sent back by the server (such as JSON error details or an HTML error page).
  • response.status: The HTTP status code returned by the server (for example, 400, 401, 404, or 500).
  • response.statusText: The status message provided by the server (for example, "Not Found" or "Internal Server Error").
  • response.headers: An object containing the HTTP response headers sent by the server.
  • response.config: The request configuration object associated with this specific response.

Categorizing Error Scenarios

Axios errors generally fall into three distinct categories based on which properties are populated:

  1. Server Responded with Error (error.response is defined): The request was received, but the server returned a non-2xx status code. Inspect error.response.status and error.response.data to handle these errors.
  2. No Response Received (error.request is defined, error.response is undefined): The request was made, but no response was received (e.g., network drop, CORS issue, or server timeout).
  3. Request Setup Error (error.request and error.response are undefined): An error occurred while setting up the request configuration before it could be sent. Inspect error.message for details.