How to Use the Axios validateStatus Property

The validateStatus configuration property in Axios defines which HTTP response status codes should resolve or reject a Promise. By default, Axios resolves responses with status codes ranging from 200 to 299 and throws an error for anything outside this range, such as 4xx client errors or 5xx server errors. This article explains the role of validateStatus, its default behavior, and how you can customize it to handle specific HTTP status codes directly in your application workflow.

Default Behavior of Axios

When you make an HTTP request using Axios without custom configuration, it uses the following default implementation for validateStatus:

validateStatus: function (status) {
  return status >= 200 && status < 300;
}

If the server returns a status code like 404 Not Found or 500 Internal Server Error, the function returns false. Axios then creates an AxiosError and rejects the Promise, redirecting the execution flow to the .catch() block or an enclosing try/catch statement.

The Role of validateStatus

The primary purpose of validateStatus is to give developers control over promise resolution based on HTTP status codes. It accepts a single argument—the HTTP status code (an integer)—and expects a boolean return value:

How to Customize validateStatus

You can apply validateStatus globally across an Axios instance or on individual requests.

1. Per-Request Configuration

To allow a specific status code (for example, 404) to resolve without throwing an exception:

axios.get('/api/users/123', {
  validateStatus: function (status) {
    return status >= 200 && status < 300 || status === 404;
  }
})
.then(response => {
  if (response.status === 404) {
    console.log('User not found, but handled as a valid response.');
  } else {
    console.log('User data:', response.data);
  }
})
.catch(error => {
  console.error('Network or 5xx server error:', error);
});

2. Instance-Level Configuration

If you want to apply custom validation logic across multiple requests, configure it within axios.create():

const apiClient = axios.create({
  baseURL: 'https://api.example.com',
  validateStatus: (status) => status < 500 // Resolve for all 2xx, 3xx, and 4xx codes
});

Common Use Cases