Explain Dio interceptors and automatic token refresh

What's really being asked

This question evaluates whether you understand HTTP middleware as stateful async machinery rather than simple decorators. The interviewer wants to see that you grasp request queuing, token lifecycle management, and error recovery in a Dart concurrency context. Specifically, they are looking for knowledge of Dio's interceptor API and how to prevent race conditions when multiple simultaneous requests hit a 401.

The full answer

First, define an interceptor as middleware implementing onRequest, onResponse, and onError hooks that mutate or short-circuit requests and responses. Second, explain the refresh flow in onError: detect a 401 or 403 via a shouldRefresh callback, lock the request queue so subsequent requests wait, then invoke an async onRefresh callback that posts to the refresh endpoint and updates a singleton TokenManager with new access and refresh tokens. Third, describe retrying the original failed request with the new token injected into the Authorization header via a TokenHeaderCallback, then unlocking the queue so queued requests automatically pick up the new token. Fourth, mention handling refresh failure with an onRefreshFailedCallback to clear state and redirect to login.

The mistakes people make

A naive answer proposes checking token expiry synchronously in onRequest and refreshing there, which blocks the request thread and ignores network latency. Another red flag is ignoring the thundering herd problem: without queue locking, ten simultaneous 401s would spawn ten separate refresh calls. Some candidates also forget to update the refresh token itself, assuming only the access token rotates, or they omit handling the case where the refresh endpoint also returns 401, leading to an infinite loop.

What usually comes next

The interviewer might ask how you would test this interceptor in unit tests without making real network calls. They could also probe how to handle partial failures when some queued requests have different header requirements, or how to add logging interceptors to the retry Dio instance without creating an infinite loop. Another follow-up is asking how to implement this without a singleton, perhaps via dependency injection.

A concrete example

Suppose a user opens a dashboard that fires three parallel API calls. All three return 401 because the access token expired. A DioRefreshInterceptor intercepts the first 401, triggers shouldRefresh, and locks the request queue. It calls onRefresh, which POSTs to /refresh with the stored refresh token, receives a new access token and refresh token, and calls tokenManager.setToken. The interceptor then retries the first request with the new Bearer header, unlocks the queue, and the remaining two queued requests automatically use the updated token via the authHeader callback. If the refresh fails, onRefreshFailedCallback clears the tokens and navigates to the login screen.