From 218bc8fbfbbdc2520130ef43652a6cd22a6e67fb Mon Sep 17 00:00:00 2001 From: Murilo Ijanc Date: Mon, 27 Jul 2026 20:42:18 -0300 Subject: Carry the municipality range on a not-found CEP MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A CEP that fails a lookup 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. The API now answers those 404s with a faixa naming the municipality whose band the number falls into, so a caller can ask "did you mean somewhere in Areal/RJ?" instead of returning a bare "not found". Cep_not_found becomes an inline record so the context rides along with the message, matching how Rate_limited and Server_error already carry theirs. It is still a 404: faixa is context on the failure and never promotes it to an address, and its bounds are the smallest and largest CEP that actually exist there — sparse across the interval, which is what the ceps count is for — not the bounds the Correios publish. Parsing is deliberately lenient. A missing, null, malformed or municipality-less faixa yields None rather than an error: a 404 is a clean answer, and no shape of this field should turn it into an Invalid_response. --- lib/cepis.mli | 55 +++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 51 insertions(+), 4 deletions(-) (limited to 'lib/cepis.mli') diff --git a/lib/cepis.mli b/lib/cepis.mli index 3deeb0b..6920a9d 100644 --- a/lib/cepis.mli +++ b/lib/cepis.mli @@ -116,6 +116,37 @@ val is_ok : health -> bool (** {1 Errors} *) +type faixa = { + localidade : string; + uf : string; + estado : string; + regiao : string; + ibge : string; + cep_ini : string; + cep_fim : string; + ceps : int; +} +(** The municipality that owns the band a {b nonexistent} CEP falls into. + + This is {b context for an error, not an address}. It arrives on + {!Cep_not_found}, the lookup still failed, and nothing here says the CEP + exists — it says which city it {i would} belong to if it did. Never promote + it to a result: the number the caller typed is not deliverable. + + It exists 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. + + [cep_ini] and [cep_fim] are the smallest and the largest CEP that + {b actually exist} in that municipality — not the bounds the Correios + publish. For Areal/RJ the DNE's own start is [25845000], which is precisely + the CEP that just failed; [cep_ini] is [25845001]. + + The range is {b sparse}, and that is what [ceps] is for. Areal's 118 CEPs + are scattered across the ~4,900 numbers between [25845001] and [25849899]. + Presenting the pair as "valid from … to …" would be wrong for about 98% of + the interval: it is a bounding box, not a list. *) + (** Everything that can go wrong, split by {b the decision the caller has to make} rather than by the HTTP status that caused it. @@ -129,9 +160,17 @@ type error = (** The CEP is not 8 digits. Usually produced {b without} a request ever being made — the client checks the format before going to the network. Retrying is pointless. *) - | Cep_not_found of string + | Cep_not_found of { message : string; faixa : faixa option } (** The CEP is well-formed but does not exist in the DNE database. - Retrying is pointless. *) + Retrying is pointless. + + [faixa] names the municipality whose band that number falls into, when + it falls into one — enough to answer "did you mean Areal/RJ?" instead + of a bare "not found". It is [None] when the CEP lands in a band no + municipality owns, and also whenever the field cannot be read: a 404 + is a clean answer, and no shape of [faixa] turns it into a + {!Invalid_response}. See {!faixa} for what its bounds do and do not + mean. *) | Rate_limited of { message : string; retry_after : float option } (** The API (or the edge in front of it) answered 429 on every attempt. [retry_after] is what the server asked for, in seconds, or [None] if @@ -155,7 +194,11 @@ val error_message : error -> string (** The human-readable message carried by an error, without its kind. *) val string_of_error : error -> string -(** The error rendered for a log line: kind, then message. *) +(** The error rendered for a log line: kind, then message. + + A {!Cep_not_found} carrying a {!faixa} names the municipality, because "CEP + 25845000 does not exist" and "…and it would have been in Areal/RJ" are two + very different lines to find in a log. *) (** {1 Validation} *) @@ -234,7 +277,11 @@ module Client : sig A 400 from the API surfaces as {!Invalid_cep} carrying the API's own message: the format already passed local validation, so the server knows - something this client does not. *) + something this client does not. + + A 404 surfaces as {!Cep_not_found}, and it may carry a {!faixa} naming the + municipality the number would have belonged to. That is context on the + failure; it never becomes an [Ok]. *) val lookup_many : t -> string list -> (address option list, error) result (** [lookup_many client ceps] resolves many CEPs in one batch. -- cgit v1.3