1 files changed, 25 insertions, 0 deletions
diff --git a/lib/src/client.dart b/lib/src/client.dart
index 9ddc165..dc0ddb8 100644
--- a/lib/src/client.dart
+++ b/lib/src/client.dart
@@ -186,6 +186,10 @@ class Client {
   /// own message: the format already passed local validation, so the server
   /// knows something this client does not.
   ///
+  /// A 404 may carry a [Faixa] on [CepNotFoundException.faixa], naming the
+  /// municipality the CEP would have belonged to. It is context for the error,
+  /// not an address, and it is `null` whenever the API did not send one.
+  ///
   /// Throws [InvalidCepException] when the CEP is not 8 digits — no request is
   /// made; [CepNotFoundException] when it is well-formed but absent from the
   /// database; [RateLimitedException] on 429 after every attempt;
@@ -200,6 +204,7 @@ class Client {
       throw CepNotFoundException(
         'CEP $number does not exist in the DNE database',
         cep: number,
+        faixa: _faixa(reply.body),
       );
     }
     if (reply.status == 400) {
@@ -458,6 +463,26 @@ String _errorMessage(String body, String fallback) {
   return fallback;
 }
 
+/// Reads the `faixa` block out of a 404 body, or returns `null`.
+///
+/// Every failure — a body that is not JSON, no `faixa` key, a `faixa` that is
+/// not an object, one that is empty — is the same `null`. The 404 is the
+/// answer the caller asked for; it must not be lost to a parse error over the
+/// hint hanging off it.
+Faixa? _faixa(String body) {
+  final Object? data;
+  try {
+    data = jsonDecode(body);
+  } on FormatException {
+    return null;
+  }
+  if (data is! Map<String, dynamic>) {
+    return null;
+  }
+  final block = data['faixa'];
+  return block is Map<String, dynamic> ? Faixa.fromJson(block) : null;
+}
+
 Duration? _retryAfter(String? value) {
   if (value == null) {
     return null;