Carry the municipality on a not-found CEPHEADv0.2.0main

A CEP that fails is rarely a random number: it is usually someone who
knows the city and guessed, most often the -000 that 957 municipalities
never received. The API now answers 404 with an optional faixa naming
the municipality that number would have belonged to, so the caller can
say "you are in Areal, but not at that number" instead of a dead end.

It stays an error. Cepis.Faixa hangs off Cepis.NotFoundError as context
for the failure, never as an address, and parsing is deliberately
tolerant: an absent, truncated or unreadable faixa yields nil rather
than costing the caller a clean definitive answer.

The bounds are the smallest and largest CEP that actually exist there,
not the range the Correios publish, and almost nothing between them is
valid — hence ceps and density/1, so nobody reads the pair as a list of
numbers to try.

1 files changed, 10 insertions, 2 deletions

diff --git a/lib/cepis/error.ex b/lib/cepis/error.ex
index bd86b65..2391c8c 100644
--- a/lib/cepis/error.ex
+++ b/lib/cepis/error.ex
@@ -21,11 +21,19 @@ defmodule Cepis.NotFoundError do
 
   `cep` holds the normalised 8 digits that were looked up. Retrying does not
   help: the answer is definitive.
+
+  `faixa` is a `Cepis.Faixa` naming the municipality that CEP *would* have
+  belonged to, or `nil`. It is context for the failure and **not** an address —
+  this is still a not-found, and the CEP is still not in the database. It is
+  `nil` whenever the number falls in a band no municipality owns, which the API
+  signals by omitting the field rather than sending null.
   """
 
-  defexception [:message, :cep]
+  alias Cepis.Faixa
+
+  defexception [:message, :cep, :faixa]
 
-  @type t :: %__MODULE__{message: String.t(), cep: String.t()}
+  @type t :: %__MODULE__{message: String.t(), cep: String.t(), faixa: Faixa.t() | nil}
 end
 
 defmodule Cepis.NetworkError do