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

A 404 that only says "not found" is correct and useless. The CEP that
fails is almost never random: it is someone who knows the city and
guessed the number, and the classic guess is the -000 that 957
municipalities never received.

The API now names the municipality on the 404, so surface it as
Error.Faixa instead of throwing the body away.

1 files changed, 33 insertions, 0 deletions

diff --git a/README.md b/README.md
index 970bbd1..8f0f07e 100644
--- a/README.md
+++ b/README.md
@@ -201,6 +201,39 @@ if errors.As(err, &cerr) && errors.Is(cerr, cepis.ErrRateLimited) {
 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.
 
+### Which city the missing CEP was from
+
+A CEP that fails is rarely a random number — it is usually someone who knows
+the city and guessed the rest. The classic guess is the `-000`: a small town
+often has a single city-wide CEP ending that way, but 957 municipalities are
+coded street by street and never got one. Areal/RJ answers from `25845-001` up,
+never at `25845-000`.
+
+When the API can name the municipality the number would fall in, it comes back
+on the error:
+
+```go
+_, err := cepis.Lookup(ctx, "25845-000")
+
+var cerr *cepis.Error
+if errors.As(err, &cerr) && cerr.Faixa != nil {
+        fmt.Printf("%s/%s has %d CEPs, from %s to %s\n",
+                cerr.Faixa.Localidade, cerr.Faixa.UF, cerr.Faixa.CEPs,
+                cerr.Faixa.CEPIni, cerr.Faixa.CEPFim)
+        // Areal/RJ has 118 CEPs, from 25845001 to 25849899
+}
+```
+
+`CEPIni` and `CEPFim` are the smallest and largest CEP that **exist** there, not
+the bounds the Correios publish — the published start is the `-000` that just
+failed. The range is sparse, which is what `CEPs` is for: those 118 are
+scattered across nearly five thousand numbers, so do not read the pair as a list
+of valid CEPs.
+
+`Faixa` is `nil` whenever the API did not send one, including for a CEP in a
+band that belongs to no municipality at all. It is an extra on top of an error
+that is complete without it.
+
 ## Development
 
 Everything runs through `make`: