diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 49 |
1 files changed, 48 insertions, 1 deletions
@@ -164,7 +164,7 @@ make**, not by the HTTP status that caused it: | variant | when | does retrying help? | | --- | --- | --- | | `InvalidCep` | not 8 digits | no | -| `NotFound` | well-formed, not in the database | no | +| `NotFound` | well-formed, not in the database; may carry a `faixa` | no | | `RateLimited` | 429; carries `retry_after` | yes, later | | `Server` | 5xx; carries `status` | yes, later | | `Network` | DNS, connection, timeout, TLS | yes, later | @@ -183,6 +183,53 @@ match cepis::lookup(&cep_from_form) { 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. +### A CEP that does not exist, and where it would be + +A failing CEP is rarely a random number: it is usually someone who knows the +city and guessed the digits, and the classic guess is the `-000` that 957 +municipalities never received. So `NotFound` carries the municipality that CEP +*would* belong to, whenever the API can place it: + +```rust +if let Err(err) = cepis::lookup("25845000") { + match err.faixa() { + Some(f) => println!("no such CEP in {}", f.municipality()), // "Areal/RJ" + None => println!("no such CEP"), + } +} +``` + +```rust +if let Some(f) = err.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 +} +``` + +Three things not to get wrong: + +- **It is still an error.** The response is still a 404 and the CEP still does + not exist. This is context for the failure, never an address. +- **`cep_ini`/`cep_fim` are not the Correios range.** They are the smallest and + largest CEP that *actually exist* in the municipality. The DNE's own start + for Areal is `25845000` — exactly the CEP that just failed. Show the official + bounds and you suggest the CEP is valid. +- **The range is sparse.** Areal's 118 CEPs are scattered over the ~4,900 + numbers between the two ends; almost none of that interval exists either. + That is what `ceps` is for — the pair is not a list, or a count, of valid + CEPs. + +`faixa` is **omitted, never null**, when the CEP falls in a band no +municipality owns, so `err.faixa()` is `None` there. It is also `None` if the +field cannot be read: an unparseable extra never turns a clean not-found into a +parse error. + ## Development Everything runs through `make`, which shells out to `cargo`: |