Report the municipality a missing CEP would have belonged toHEADv0.2.0main

A CEP that fails a lookup is rarely a random number: it is usually someone
who knows the city and guessed, and the classic guess is the -000 that 957
municipalities never received. The API now answers those 404s with a faixa
naming the municipality that owns the band the number fell into, which is
the difference between telling a user "invalid CEP" and "no such CEP in
Areal/RJ".

It is context for an error and never an address, so it rides on the
cepis_not_found condition instead of turning the failure into a success,
and cep_ini/cep_fim are the endpoints that exist rather than the range the
Correios publish - the interval between them is sparse, which is what ceps
counts. Parsing is deliberately unable to signal: a faixa that is null, an
array, a string or half a body leaves a clean not-found behind, because the
caller asked for the CEP, not for the decoration on its absence.

1 files changed, 56 insertions, 1 deletions

diff --git a/README.md b/README.md
index 64baf53..521aa42 100644
--- a/README.md
+++ b/README.md
@@ -167,7 +167,7 @@ Failures are classed conditions. Everything inherits `cepis_error` (and
 | class | when | does retrying help? |
 | --- | --- | --- |
 | `cepis_invalid_cep` | not 8 digits | no |
-| `cepis_not_found` | well-formed, not in the database | no |
+| `cepis_not_found` | well-formed, not in the database; carries `faixa` | no |
 | `cepis_rate_limited` | 429; carries `retry_after` | yes, later |
 | `cepis_server_error` | 5xx; carries `status` | yes, later |
 | `cepis_network_error` | DNS, connection, timeout, TLS | yes, later |
@@ -185,6 +185,61 @@ tryCatch(
 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.
 
+### Where a CEP that does not exist would have been
+
+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. When the number falls inside the range of a
+municipality, `cepis_not_found` carries a `faixa` naming it:
+
+```r
+tryCatch(
+  cep_lookup("25845000"),
+  cepis_not_found = function(e) {
+    if (is.null(e$faixa)) {
+      "no such CEP"
+    } else {
+      paste0("no such CEP in ", e$faixa$localidade, "/", e$faixa$uf)
+    }
+  }
+)
+#> "no such CEP in Areal/RJ"
+```
+
+The lookup **still failed**, and a `faixa` is not an address — it is context
+for the error, and answers "did you mean somewhere in Areal?" instead of
+"invalid CEP". The condition is the same `cepis_not_found` as before; code
+that ignores `faixa` keeps working.
+
+```r
+f <- e$faixa
+
+f$localidade   # "Areal"
+f$uf           # "RJ"
+f$estado       # "Rio de Janeiro"
+f$regiao       # "Sudeste"
+f$ibge         # "3300225"
+f$cep_ini      # "25845001"
+f$cep_fim      # "25849899"
+f$ceps         # 118
+```
+
+Two things about `cep_ini` and `cep_fim`:
+
+- They are the smallest and the largest CEP 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 above.
+- **The range is sparse.** Areal's 118 CEPs are scattered over the ~4900
+  numbers between the two endpoints. `ceps` is there so that is visible:
+  never present the pair as a list of valid CEPs, and never iterate from one
+  to the other.
+
+`faixa` is `NULL` when the CEP falls in a band no municipality owns. The API
+omits the field rather than sending null, so `is.null(e$faixa)` says the
+number is close to nothing, not that the fields came back blank. Batches do
+not report it either: `cep_lookup_many()` still gives `NULL` at that
+position, because the endpoint behind it is CSV.
+
 ## Development
 
 Everything runs through `make`: