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

A CEP that fails is almost never random: it is someone who knows the city
and guessed the number, usually the -000 that 957 municipalities never
received. The API now answers those 404s with a faixa block naming the
municipality that owns the band, so CepNotFoundException exposes it and
says it in its message.

It stays an error. The band is context, not an address, and its cep_ini
and cep_fim are the smallest and largest CEP that actually exist there —
not the bounds the Correios publish, and not a dense interval — so the
type documents both traps rather than inviting callers to walk the range.

Reading it is best effort: a missing, malformed or oddly shaped faixa is
dropped, because turning a definitive answer about the request into a
parse failure would hide the answer.

1 files changed, 42 insertions, 3 deletions

diff --git a/README.md b/README.md
index 599a25e..d75b2c4 100644
--- a/README.md
+++ b/README.md
@@ -26,7 +26,7 @@ cd cepis-java
 make build
 ```
 
-That writes `build/cepis-0.1.0.jar`; put it on the classpath.
+That writes `build/cepis-0.2.0.jar`; put it on the classpath.
 
 ## Usage
 
@@ -162,7 +162,7 @@ Client client = Client.builder().baseUrl("http://localhost:8080").build();
 From the command line, to confirm quickly that it answers:
 
 ```sh
-java -jar build/cepis-0.1.0.jar --base-url http://localhost:8080 01001000
+java -jar build/cepis-0.2.0.jar --base-url http://localhost:8080 01001000
 ```
 
 ## Errors
@@ -174,7 +174,7 @@ 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 |
@@ -198,6 +198,45 @@ more.
 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.
 
+### The municipality behind a CEP that does not exist
+
+A CEP that fails is rarely random: it is usually someone who knows the city and
+guessed the number — the classic guess being the `-000`, which 957
+municipalities never received. So a `CepNotFoundException` may name the
+municipality whose band the CEP fell in:
+
+```java
+try {
+    Address address = Cepis.lookup("25845-000");
+} catch (CepNotFoundException e) {
+    e.faixa().ifPresent(faixa -> {
+        faixa.describe();    // "Areal/RJ"
+        faixa.localidade();  // "Areal"
+        faixa.ibge();        // "3300225"
+        faixa.cepIni();      // "25845001"
+        faixa.cepFim();      // "25849899"
+        faixa.ceps();        // 118
+    });
+}
+```
+
+Three things to keep straight, because getting any of them wrong is worse than
+not having the field at all:
+
+- **It is still a 404.** This is context for the error, not an address. Do not
+  let it turn a not-found into a success — the CEP asked for does not exist.
+- **`cepIni` and `cepFim` are the smallest and the largest CEP that *actually
+  exist* there**, not the bounds the Correios publish. The DNE's own start for
+  Areal is `25845000`, which is exactly the CEP that just failed.
+- **The interval is sparse.** Areal's 118 CEPs are spread over some 9000
+  numbers, so almost nothing between the two exists. That is what `ceps()` is
+  for. Never present the pair as a range, or a list, of valid CEPs.
+
+`faixa()` is empty whenever the CEP fell in a band no municipality owns; the API
+omits the field in that case rather than sending null. A `faixa` that is
+malformed, empty or of the wrong shape is dropped the same way: the not-found
+itself is never at risk of becoming a parse failure.
+
 ## Development
 
 Everything runs through `make` and the JDK. There is nothing to install first