1 files changed, 40 insertions, 0 deletions
diff --git a/README.md b/README.md
index dba6aa2..20f2cfa 100644
--- a/README.md
+++ b/README.md
@@ -184,6 +184,46 @@ except CepisError:
 so code already handling those types during input validation keeps working
 without knowing this library exists.
 
+### Which municipality the CEP would have been in
+
+A CEP that fails is rarely random: it is usually someone who knows the city and
+guessed the number — and the classic guess is the `-000` that 957
+municipalities never received. So `CEPNotFound` carries `faixa`, the
+municipality that CEP would have belonged to, when the API can work it out:
+
+```python
+try:
+    address = cepis.lookup("25845-000")
+except CEPNotFound as exc:
+    if exc.faixa:
+        f = exc.faixa
+        f.localidade  # 'Areal'
+        f.uf  # 'RJ'
+        f.estado  # 'Rio de Janeiro'
+        f.regiao  # 'Sudeste'
+        f.ibge  # '3300225'
+        f.label  # 'Areal/RJ'
+        f.cep_ini  # '25845001'
+        f.cep_fim  # '25849899'
+        f.ceps  # 118
+        print(f"That CEP does not exist. Did you mean somewhere in {f.label}?")
+```
+
+Three things about it:
+
+- **It is still a 404.** `faixa` is context for the error, never an address.
+  `lookup` raises exactly as before; nothing here says the CEP exists.
+- **`cep_ini` and `cep_fim` are the CEPs that really exist**, not the bounds
+  the Correios publish. The DNE's own start for Areal is `25845000` — precisely
+  the CEP that just failed, which is why the range starts one above it.
+- **The range is sparse.** Areal's 118 CEPs are scattered across the ~4,900
+  numbers between `25845001` and `25849899`. That is what `ceps` is for: never
+  read the pair as a list of valid CEPs, and do not iterate it.
+
+`faixa` is `None` when the CEP falls in a band no municipality owns — the API
+**omits** the field there rather than sending null — and also when talking to
+an API older than the field. Always test it before use.
+
 `InvalidResponse` almost always means something between you and the 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.