Name the municipality behind a CEP that does not existHEADv0.2.0main

The API now hangs an optional faixa block off the 404 of GET /{cep}, and
this exposes it as CepNotFoundException.Faixa. A CEP that fails is rarely
random: it is usually someone who knows the city and guessed the number,
most often the -000 that 957 municipalities never received. Knowing where
the guess landed turns a dead-end "CEP not found" into a question worth
asking the user.

It stays an error. The block names the municipality the number would
belong to, never an address, and the lookup still throws. CepIni and
CepFim are the smallest and largest CEP that actually exist there, not the
range the Correios publish — the published start for Areal is 25845000,
exactly the CEP that fails — and the interval between them is sparse,
which is what Ceps is for.

Parsing is deliberately toothless: absent, misshapen or nameless, the
block becomes null and the caller gets the same clean not-found it got
before the field existed. A courtesy on top of a 404 must never be able to
turn it into a parse failure.

1 files changed, 48 insertions, 2 deletions

diff --git a/README.md b/README.md
index 8d25149..d1df236 100644
--- a/README.md
+++ b/README.md
@@ -23,7 +23,7 @@ cd cepis-csharp
 make pack
 ```
 
-That writes `artifacts/Cepis.0.1.0.nupkg`; add it from a local feed, or
+That writes `artifacts/Cepis.0.2.0.nupkg`; add it from a local feed, or
 reference `src/Cepis/Cepis.csproj` directly.
 
 ## Usage
@@ -190,7 +190,7 @@ decision you have to make**, not by the HTTP status that caused it:
 | error | when | does retrying help? |
 | --- | --- | --- |
 | `InvalidCepException` | not 8 digits | no |
-| `CepNotFoundException` | well-formed, not in the database | no |
+| `CepNotFoundException` | well-formed, not in the database; may carry `Faixa` | no |
 | `RateLimitedException` | 429; carries `RetryAfter` | yes, later |
 | `ServerErrorException` | 5xx; carries `Status` | yes, later |
 | `NetworkException` | DNS, connection, timeout, TLS | yes, later |
@@ -220,6 +220,52 @@ A cancellation you asked for is not a `CepisException` — it surfaces as
 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.
 
+### A CEP that does not exist
+
+A 404 is still a 404: `LookupAsync` throws `CepNotFoundException` and there is
+no address. What the exception may add is `Faixa`, the municipality that CEP
+*would* have belonged to:
+
+```csharp
+try
+{
+    Address address = await client.LookupAsync("25845000");
+}
+catch (CepNotFoundException e) when (e.Faixa is { } faixa)
+{
+    faixa.Localidade;  // "Areal"
+    faixa.UF;          // "RJ"
+    faixa.Estado;      // "Rio de Janeiro"
+    faixa.Ibge;        // "3300225"
+    faixa.CepIni;      // "25845001"
+    faixa.CepFim;      // "25849899"
+    faixa.Ceps;        // 118
+    // "we don't have that CEP — did you mean a street in Areal/RJ?"
+}
+```
+
+Worth handling, because a CEP that fails is rarely random: it is usually
+someone who knows the city and guessed the number. The classic guess is the
+`-000`, which 957 municipalities never received — `25845000` above is Areal's.
+
+Three things not to get wrong:
+
+- **It is context for an error, not an address.** Nothing in it says the CEP
+  exists. Filling a form from these fields is inventing an address.
+- **`CepIni` and `CepFim` are what exists, not what the Correios publish.** The
+  DNE's own range for Areal starts at `25845000` — the CEP that just failed.
+  `CepIni` is `25845001`, the smallest one actually in the database.
+- **The range is sparse.** Areal's 118 CEPs are spread across the ~4,900
+  numbers between its two ends. That is what `Ceps` is for; never walk the
+  interval, and never show the pair as a list of valid CEPs.
+
+`Faixa` is `null` whenever the API named no municipality: a CEP in a band
+nobody owns, an older API, or a block this client could not read. The API
+**omits** the field rather than sending a null, and an unreadable one is
+dropped instead of failing the lookup — a courtesy on top of a 404 must not
+turn a clean not-found into a parse error. Absence is the ordinary case; treat
+it as one.
+
 ## Development
 
 Everything runs through `make` and the .NET SDK: