1 files changed, 40 insertions, 1 deletions
diff --git a/README.md b/README.md
index bb79b2a..837251a 100644
--- a/README.md
+++ b/README.md
@@ -13,7 +13,7 @@ Correios data (DNE), refreshed every two weeks.
 
 ```elixir
 def deps do
-  [{:cepis, git: "https://git.cep.is/elixir.git", tag: "v0.1.0"}]
+  [{:cepis, git: "https://git.cep.is/elixir.git", tag: "v0.2.0"}]
 end
 ```
 
@@ -185,6 +185,45 @@ end
 API is answering instead of it — a captive Wi-Fi portal, a corporate proxy, an
 HTML error page. Useful as a diagnosis: the problem is not in your code.
 
+### When the CEP does not exist
+
+A failing CEP is rarely random: it is usually someone who knows the city and
+guessed the number, most often the `-000`, which 957 municipalities never
+received. So `Cepis.NotFoundError` carries a `faixa` naming the municipality
+that number *would* have belonged to, when there is one:
+
+```elixir
+{:error, %Cepis.NotFoundError{faixa: faixa}} = Cepis.lookup("25845-000")
+
+if faixa do
+  faixa.localidade   # "Areal"
+  faixa.uf           # "RJ"
+  faixa.ibge         # "3300225"
+  faixa.ceps         # 118
+  faixa.cep_ini      # "25845001"
+  faixa.cep_fim      # "25849899"
+end
+```
+
+This is **still a not-found**. The CEP is not in the database, `lookup/2` still
+returns `{:error, _}`, and `faixa` is context for the failure — never an
+address. What it buys you is a better answer to the user: "you are in Areal,
+but not at that number", instead of a dead end.
+
+Two things about it:
+
+- `cep_ini` and `cep_fim` are the smallest and the largest CEP that **actually
+  exist** in the municipality, not the bounds the Correios publish. The DNE's
+  own start for Areal is `25845000` — exactly the CEP that just failed.
+- **The range is sparse.** Almost nothing between the two bounds is a valid
+  CEP: Areal has 118 across thousands of numbers. That is what `ceps` is for,
+  and `Cepis.Faixa.density/1` measures it. Never expand the pair into a list of
+  CEPs to try.
+
+`faixa` is `nil` whenever the number falls in a band no municipality owns — the
+API omits the field there rather than sending null — so every caller has to
+handle its absence.
+
 ## Development
 
 Everything runs through `make`, which shells out to `mix`: