Duplicate token refreshes when multiple Axios requests receive 401

Answer the exact question first

Use a module‑level refreshPromise that is created once when the first 401 is seen. All subsequent 401 handlers simply return refreshPromise; after the refresh resolves, the original request is retried with the new token. This guarantees a single network call regardless of how many concurrent requests hit 401.

Likely explanation

Axios has no built‑in queue for 401‑triggered refreshes. When two or more requests finish simultaneously with 401, each response interceptor runs in isolation and starts its own refresh request. The race can lead to duplicate refreshes and inconsistent token state.

Confirmed facts

• Interceptor execution order is strictly the order of registration; there is no config to change it.
• Axios 0.27+ (the current LTS) exposes axios.interceptors.request.use and axios.interceptors.response.use but no queue or deduplication primitives.
• Sharing a promise at the module or instance level is a proven pattern in many projects and is fully compatible with Axios core.

Step‑by‑step solution for this case

1. Store the refresh promise

   let refreshPromise = null;
   

2. Request interceptor: attach scoped token

   axios.interceptors.request.use(config => {
     // Assume a function getScopedToken(config) that returns the token for the scopes needed by this request.
     const token = getScopedToken(config);
     if (token) {
       config.headers.Authorization = `Bearer ${token}`;
     }
     return config;
   });
   

3. Response interceptor: deduplicate refresh

   axios.interceptors.response.use(undefined, async error => {
     const { config, response } = error;
     if (!response || response.status !== 401) return Promise.reject(error);
   
     // If a refresh is already in flight, wait for it.
     if (!refreshPromise) {
       refreshPromise = refreshToken();
       refreshPromise.finally(() => { refreshPromise = null; });
     }
   
     try {
       await refreshPromise;
       // Retry the original request with the new token.
       config.headers.Authorization = `Bearer ${getScopedToken(config)}`;
       return axios(config);
     } catch (refreshError) {
       // If refresh failed, propagate the original 401.
       return Promise.reject(error);
     }
   });
   

4. Implementation notes
   • refreshToken() should return a promise that resolves when the new token is stored (e.g., in localStorage or a state store).
   • When using multiple axios.create() instances, each instance must maintain its own refreshPromise to avoid cross‑service interference.
   • Ensure the retry logic uses the same scoping logic as the initial request so that the retried request carries only the required scopes.
5. Verification
   • Unit test: mock the refresh endpoint, fire two identical requests that both return 401, and assert that the refresh mock is called once.
   • Integration test: spy on the interceptor, confirm that after the first 401 the promise is pending and subsequent 401 handlers await the same promise.
   • Manual check: watch the Network tab – only one refresh call should appear even when many requests hit 401.

Ask for missing diagnostic detail

If you are using separate Axios instances or a custom token‑retrieval strategy, let me know so I can tailor the code to that setup.

Answers to the specific questions

1. Pattern: module‑level shared refreshPromise with a finally block to clear it.
2. Integration: place the shared promise in the response interceptor, retry the original request with the updated scoped token after the promise resolves.
3. Interceptor order: no Axios config changes can alter the order; you must register the request interceptor before the response interceptor to ensure the token is set before any 401 can occur.