Overview

This codelab takes you from a bare Dio client to a disciplined networking layer that you can reuse across apps by treating the HTTP path as a pipeline where each cross cutting concern lives in one place and is easy to reason about. You start by creating a base client with strict timeouts, consistent JSON handling, and structured logging that is safe for development and redacted for production. You then define a tiny ApiError type and a mapper from DioException to a compact set of error kinds such as network, timeout, unauthorized, server, and parse so that screens never branch on status codes or exception classes directly. With error semantics in place you add an authentication interceptor that attaches the access token to eligible requests, detects 401 responses, and runs a single refresh for concurrent callers using a shared Future while Dio is locked to prevent new requests from leaving with stale credentials. After refresh completes, the original request is replayed with the new token so calling code remains unaware of the dance. You then add a retry interceptor that targets only idempotent methods, uses exponential backoff with jitter, carries attempt count in RequestOptions.extra, and bails on nontransient errors to avoid accidental duplicate writes. Finally you wire these parts into a small ApiClient that exposes clear methods like login and fetchPosts, validates response shapes defensively, and shields the UI from transport details. Along the way you learn why status validation should be centralized, why refresh endpoints must ignore Authorization headers, how to prevent request storms during token expiry, and how a few small conventions around arguments, headers, and logging can turn a fragile tangle of network code into a predictable system that fails gracefully and recovers quickly.