Initial importv0.1.0

1 files changed, 42 insertions, 0 deletions

diff --git a/man/cepis_conditions.Rd b/man/cepis_conditions.Rd
new file mode 100644
index 0000000..4def4ff
--- /dev/null
+++ b/man/cepis_conditions.Rd
@@ -0,0 +1,42 @@
+% 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.
+}