diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 48 |
1 files changed, 47 insertions, 1 deletions
@@ -252,6 +252,52 @@ Errors stringify to their message, so `warn $err` and `"$err"` do the obvious thing. `$err->retry_after` carries what the server asked for, in seconds, and `$err->status` the HTTP status of the last attempt. +### A not-found that knows where it was + +A `Cepis::Error::CEPNotFound` often knows **which municipality** the CEP would +have belonged to. When it does, `$err->faixa` is a `Cepis::Faixa`: + +```perl +my $address = eval { Cepis::lookup('25845000') }; + +if ( !$address && ref $@ && $@->isa('Cepis::Error::CEPNotFound') ) { + if ( my $faixa = $@->faixa ) { + $faixa->localidade; # "Areal" + $faixa->uf; # "RJ" + $faixa->ibge; # "3300225" + $faixa->ceps; # 118 + $faixa->cep_ini; # "25845001" + $faixa->cep_fim; # "25849899" + $faixa->label; # "Areal/RJ" + } +} +``` + +The message names the municipality too: + +``` +CEP 25845000 does not exist in the DNE database (it would fall in Areal/RJ) +``` + +Worth checking, because a failing CEP 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. + +Three things this is not: + +- **It is not a success.** The response is still a 404 and `lookup` still + throws. `faixa` is context for the error, never an address. +- **It is not always there.** When the CEP falls in a band no municipality owns, + the API omits the block — `$err->faixa` is then `undef`, never a null-ish + empty object. A malformed block is dropped the same way rather than turning a + clean not-found into a parse failure. +- **`cep_ini`..`cep_fim` is not a list of valid CEPs.** They 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`, exactly the CEP that + just failed. And the range is sparse: Areal's 118 CEPs are scattered across + the ~4,900 numbers between them. That is what `ceps` is for. Do not iterate + the interval. + `Cepis::Error::InvalidResponse` almost always means something between you and the 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. @@ -269,7 +315,7 @@ bring up a real HTTP server on loopback. make # list the targets make test # run the suite with prove make lint # perl -c over lib, t and Makefile.PL -make build # build Cepis-0.1.0.tar.gz +make build # build Cepis-0.2.0.tar.gz make check # lint, then test, then build ``` |