How do you structure networking and API error handling?

I keep transport concerns in one client and map responses into domain models. The UI should not know about status codes. Timeouts, cancellation, retry policy and auth refresh belong at that boundary, with logging that redacts tokens and personal data.

Future<List<Repo>> fetchRepos(http.Client client) async {
  final uri = Uri.parse('https://api.example.com/repos');
  final response = await client
      .get(uri, headers: {'Accept': 'application/json'})
      .timeout(const Duration(seconds: 10));

  if (response.statusCode != 200) {
    throw ApiException('HTTP ' + response.statusCode.toString());
  }

  final decoded = jsonDecode(response.body) as List<dynamic>;
  return decoded
      .map((item) => Repo.fromJson(item as Map<String, dynamic>))
      .toList();
}

• Set connect and receive timeouts; the default may be too long for mobile networks
• Retry with exponential backoff and jitter only for transient, idempotent failures
• Do not retry a payment or create call unless the server supports idempotency keys
• Cancel requests when the screen is disposed or superseded
• Never log authorization headers, tokens or full response bodies containing personal data

Auth refresh and errors

Handle token refresh in one interceptor or client wrapper, serialising concurrent refreshes so many requests do not trigger many refreshes. Map network, timeout, unauthorised, rate limited and server errors into distinct states. The UI needs to tell the user whether retrying is useful.