diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 50 |
1 files changed, 48 insertions, 2 deletions
@@ -23,7 +23,7 @@ cd cepis-csharp make pack ``` -That writes `artifacts/Cepis.0.1.0.nupkg`; add it from a local feed, or +That writes `artifacts/Cepis.0.2.0.nupkg`; add it from a local feed, or reference `src/Cepis/Cepis.csproj` directly. ## Usage @@ -190,7 +190,7 @@ decision you have to make**, not by the HTTP status that caused it: | error | when | does retrying help? | | --- | --- | --- | | `InvalidCepException` | not 8 digits | no | -| `CepNotFoundException` | well-formed, not in the database | no | +| `CepNotFoundException` | well-formed, not in the database; may carry `Faixa` | no | | `RateLimitedException` | 429; carries `RetryAfter` | yes, later | | `ServerErrorException` | 5xx; carries `Status` | yes, later | | `NetworkException` | DNS, connection, timeout, TLS | yes, later | @@ -220,6 +220,52 @@ A cancellation you asked for is not a `CepisException` — it surfaces as 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. +### A CEP that does not exist + +A 404 is still a 404: `LookupAsync` throws `CepNotFoundException` and there is +no address. What the exception may add is `Faixa`, the municipality that CEP +*would* have belonged to: + +```csharp +try +{ + Address address = await client.LookupAsync("25845000"); +} +catch (CepNotFoundException e) when (e.Faixa is { } faixa) +{ + faixa.Localidade; // "Areal" + faixa.UF; // "RJ" + faixa.Estado; // "Rio de Janeiro" + faixa.Ibge; // "3300225" + faixa.CepIni; // "25845001" + faixa.CepFim; // "25849899" + faixa.Ceps; // 118 + // "we don't have that CEP — did you mean a street in Areal/RJ?" +} +``` + +Worth handling, because a CEP that fails is rarely random: it is usually +someone who knows the city and guessed the number. The classic guess is the +`-000`, which 957 municipalities never received — `25845000` above is Areal's. + +Three things not to get wrong: + +- **It is context for an error, not an address.** Nothing in it says the CEP + exists. Filling a form from these fields is inventing an address. +- **`CepIni` and `CepFim` are what exists, not what the Correios publish.** The + DNE's own range for Areal starts at `25845000` — the CEP that just failed. + `CepIni` is `25845001`, the smallest one actually in the database. +- **The range is sparse.** Areal's 118 CEPs are spread across the ~4,900 + numbers between its two ends. That is what `Ceps` is for; never walk the + interval, and never show the pair as a list of valid CEPs. + +`Faixa` is `null` whenever the API named no municipality: a CEP in a band +nobody owns, an older API, or a block this client could not read. The API +**omits** the field rather than sending a null, and an unreadable one is +dropped instead of failing the lookup — a courtesy on top of a 404 must not +turn a clean not-found into a parse error. Absence is the ordinary case; treat +it as one. + ## Development Everything runs through `make` and the .NET SDK: |