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, 27 insertions, 0 deletions

diff --git a/man/cepis_conditions.Rd b/man/cepis_conditions.Rd
index 4def4ff..9b25cbe 100644
--- a/man/cepis_conditions.Rd
+++ b/man/cepis_conditions.Rd
@@ -40,3 +40,30 @@ 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.
 }
+\section{What cepis_not_found carries}{
+
+\code{cep}, the 8 digits as they went to the API, and \code{faixa}: a \link{cepis_faixa}
+naming the municipality that owns the band of numbers the CEP fell into,
+or \code{NULL} when it fell in a band nobody owns. The API omits it, it never
+sends null, so \code{NULL} here is the same statement.
+
+It changes nothing about the answer — the CEP still does not exist, and a
+\code{faixa} is not an address — but it is usually the difference between
+telling someone "invalid CEP" and telling them "no such CEP in Areal/RJ":
+
+\if{html}{\out{<div class="sourceCode r">}}\preformatted{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)
+    \}
+  \}
+)
+}\if{html}{\out{</div>}}
+
+The CEP that failed above is the DNE's own first number for Areal, and it
+is the shape of guess this field is for.
+}
+