% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/conditions.R
\name{cepis_conditions}
\alias{cepis_conditions}
\title{Conditions signalled by cepis}
\description{
Every failure raised by this package is a classed condition inheriting
from \code{cepis_error}, so one handler catches all of them:

\if{html}{\out{<div class="sourceCode r">}}\preformatted{tryCatch(
  cep_lookup(cep_from_form),
  cepis_not_found = function(e) NULL,
  cepis_error = function(e) reschedule()
)
}\if{html}{\out{</div>}}

Below \code{cepis_error} the split is by \strong{the decision you have to make}, not
by the HTTP status that caused it:\tabular{lll}{
   class \tab when \tab does retrying help? \cr
   \code{cepis_invalid_cep} \tab not 8 digits \tab no \cr
   \code{cepis_not_found} \tab well-formed, not in the database \tab no \cr
   \code{cepis_rate_limited} \tab 429 \tab yes, later \cr
   \code{cepis_server_error} \tab 5xx \tab yes, later \cr
   \code{cepis_network_error} \tab DNS, connection, timeout, TLS \tab yes, later \cr
   \code{cepis_invalid_response} \tab unintelligible response \tab probably not \cr
}


That split is why \code{cepis_not_found} is not "the HTTP 404 condition": it is
also signalled with no request made at all, when the CEP is malformed
before it ever leaves the machine.

Each condition carries the fields a caller needs to act on it:
\code{cepis_rate_limited} has \code{retry_after} (seconds the server asked for, or
\code{NULL}), \code{cepis_server_error} has \code{status}, \code{cepis_network_error} has
\code{url}, and \code{cepis_invalid_cep} has \code{value}, the input as it arrived.

\code{cepis_invalid_response} 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.
}
\section{What cepis_not_found carries}{

\code{cep}, the 8 digits as they went to the API, and \code{faixa}: a \link{cepis_faixa}
naming the municipality that owns the band of numbers the CEP fell into,
or \code{NULL} when it fell in a band nobody owns. The API omits it, it never
sends null, so \code{NULL} here is the same statement.

It changes nothing about the answer — the CEP still does not exist, and a
\code{faixa} is not an address — but it is usually the difference between
telling someone "invalid CEP" and telling them "no such CEP in Areal/RJ":

\if{html}{\out{<div class="sourceCode r">}}\preformatted{tryCatch(
  cep_lookup("25845000"),
  cepis_not_found = function(e) \{
    if (is.null(e$faixa)) \{
      "no such CEP"
    \} else \{
      paste0("no such CEP in ", e$faixa$localidade, "/", e$faixa$uf)
    \}
  \}
)
}\if{html}{\out{</div>}}

The CEP that failed above is the DNE's own first number for Areal, and it
is the shape of guess this field is for.
}