1 files changed, 19 insertions, 1 deletions
diff --git a/lib/cepis/errors.rb b/lib/cepis/errors.rb
index 7a15841..71b8a29 100644
--- a/lib/cepis/errors.rb
+++ b/lib/cepis/errors.rb
@@ -27,7 +27,25 @@ module Cepis
   class InvalidCEP < Error; end
 
   # The CEP is well-formed but does not exist in the DNE database.
-  class CEPNotFound < Error; end
+  class CEPNotFound < Error
+    # The municipality that owns the band this CEP falls into, as a {Faixa},
+    # or `nil` when no municipality owns it — or when the API did not say.
+    #
+    # It is context for the failure, not a fallback address: the CEP asked for
+    # does not exist, and this only names the neighbourhood of numbers it
+    # would have belonged to. Useful because a CEP that fails is usually a
+    # guess by someone who knows the city, so the municipality is the one
+    # thing about it that tends to be right.
+    #
+    # Read {Faixa} before showing `cep_ini`/`cep_fim` to anyone: the band is
+    # sparse, and the pair is not a range of valid CEPs.
+    attr_reader :faixa
+
+    def initialize(message, faixa: nil)
+      super(message)
+      @faixa = faixa
+    end
+  end
 
   # The request never completed: DNS, refused connection, timeout, TLS.
   #