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, 4 insertions, 1 deletions

diff --git a/man/cep_lookup.Rd b/man/cep_lookup.Rd
index 3c22a1e..f6f2d0b 100644
--- a/man/cep_lookup.Rd
+++ b/man/cep_lookup.Rd
@@ -23,7 +23,10 @@ has for it, including the coordinate when there is one.
 
 \describe{
 \item{\code{cepis_invalid_cep}}{the CEP is not 8 digits. No request is made.}
-\item{\code{cepis_not_found}}{well-formed, but not in the database.}
+\item{\code{cepis_not_found}}{well-formed, but not in the database. Carries
+\code{faixa}, a \link{cepis_faixa} naming the municipality whose range the CEP
+fell into, when it fell into one. Still a not-found: the CEP does not
+exist, and a \code{faixa} is not an address.}
 \item{\code{cepis_rate_limited}}{429 on every attempt.}
 \item{\code{cepis_server_error}}{5xx on every attempt.}
 \item{\code{cepis_network_error}}{the request never completed.}