Axios Interceptors: Middleware for Your API Calls

WHY IT EXISTS Axios Interceptors solve the problem of repetitive, cross-cutting concerns in API calls. Instead of adding an authentication header or a response handler to every single axios.get() or axios.post(), you can define that logic once and have it apply globally to all requests.

THE MENTAL MODEL Think of interceptors as checkpoints on the highway of an HTTP request. A request must pass through all 'request' interceptors before it leaves your app. When the server's response comes back, it must pass through all 'response' interceptors before your application code receives it. Each checkpoint can inspect, modify, or even stop the traffic.

HOW IT WORKS You add functions using axios.interceptors.request.use() and axios.interceptors.response.use(). Each .use() call takes two functions: one for the success path and one for the error path. A request interceptor's success function receives the request config object and must return it (or a promise that resolves with it) to continue the chain. A response interceptor receives the response object. If you don't return the config or response, the chain breaks and the request will hang.

WHEN TO USE IT Interceptors are ideal for global logic. Three common use cases: first, automatically adding authentication tokens (like a JWT) to the headers of all outgoing requests. Second, creating a global error handler to catch specific HTTP status codes, like a 401 Unauthorized, and redirecting the user to a login page. Third, logging all network requests and responses for debugging.

WHEN NOT TO USE IT Avoid interceptors for logic specific to a single API call; in that case, modify the request's config object directly. Overusing interceptors for highly conditional logic can make the data flow difficult to trace. If you need conditional execution, use the runWhen option to specify when an interceptor should run, rather than putting complex if statements inside the interceptor itself.

ONE CANONICAL EXAMPLE The most common footgun is the execution order. Request interceptors are LIFO (Last-In, First-Out), meaning the last one you add is the first one to run. Response interceptors are FIFO (First-In, First-Out), running in the order they were added. For example, if you add an auth interceptor then a logging interceptor, the logger will run first on the request, but the auth handler will run first on the response. This reversal can lead to unexpected behavior if your interceptors depend on each other.