Carry the municipality of a CEP that does not existHEADv0.2.0main

A CEP that fails is rarely a random number: it is someone who knows the
city and guessed the digits, and the classic guess is the -000 that 957
municipalities never received. The API now answers the 404 with the
municipality that band belongs to, which is enough to tell the user
"Areal/RJ, but not that number" instead of a bare failure.

It stays an error. Faixa hangs off CEPNotFound rather than becoming a
result, cep_ini/cep_fim are documented as the CEPs that exist there and
not as a range to iterate, and an absent or unreadable block yields
undefined so that context can never cost the caller the clean not-found
it was already getting.

1 files changed, 41 insertions, 0 deletions

diff --git a/README.md b/README.md
index 009f7df..71e68a1 100644
--- a/README.md
+++ b/README.md
@@ -192,6 +192,47 @@ try {
 
 `RateLimited` exposes `retryAfterMs` and `ServerError` exposes `status`.
 
+### When the CEP does not exist
+
+`CEPNotFound` may carry a `faixa`: the municipality the CEP _would_ belong to.
+A failing CEP is rarely random — it is someone who knows the city and guessed
+the number, and the classic guess is the `-000` that 957 municipalities never
+received.
+
+```ts
+import { CEPNotFound, lookup } from "cepis";
+
+try {
+  await lookup("25845000");
+} catch (error) {
+  if (error instanceof CEPNotFound && error.faixa) {
+    error.faixa.localidade; // "Areal"
+    error.faixa.uf; // "RJ"
+    error.faixa.ibge; // "3300225"
+    error.faixa.cep_ini; // "25845001"
+    error.faixa.cep_fim; // "25849899"
+    error.faixa.ceps; // 118
+    error.faixa.label; // "Areal/RJ"
+  }
+}
+```
+
+Three things about it:
+
+- **It is still a 404.** `faixa` is context for the error, never an address.
+  Showing "did you mean a CEP in Areal/RJ?" is the point; treating it as a
+  result is a wrong delivery.
+- **`cep_ini`/`cep_fim` are the CEPs that actually exist there**, not the range
+  the Correios publish. The DNE's own start for Areal is `25845000` — exactly
+  the CEP that just failed.
+- **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: the
+  pair is not a list of valid CEPs, and iterating it yields mostly 404s.
+
+When the CEP falls in a band no municipality owns, the API **omits** the field
+and `error.faixa` is `undefined` — never `null`. A missing or unreadable
+`faixa` never turns a clean not-found into a parse failure.
+
 `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.