The user-facing sentence for an outcome

Every error field in the package is produced here, so the seven statuses cannot drift apart and an application can replace all of them at once.

Usage

status_message(
  source = "API",
  status = "error",
  http = NA_integer_,
  condition = NULL
)

Arguments

source

A friendly label for the service, for example "gnomAD".

status

One of STATUS_LEVELS.

http

An HTTP status code, or NA_integer_ when no response arrived.

condition

A caught condition, used when no response arrived.

Value

A single string, or NULL for a status that carries no message.

Supplying your own wording

Set biohttp.status_message to a function of source, status, http and condition. It is called instead of the built-in, and it is the way to keep an app's own voice, or to localise, while adopting the transport:

options(biohttp.status_message = function(source, status, http, condition) {
  if (identical(status, "timeout")) {
    paste0(source, " took too long. Please try again shortly.")
  } else {
    NULL  # fall through to the built-in for everything else
  }
})

Returning anything other than a single non-empty string falls back to the built-in, so covering one case and leaving the rest is expected rather than an error.

An override cannot break the return-a-value contract. It runs inside a tryCatch(), and a function that raises is treated as though it returned nothing. This matters because the override runs on the failure path, which is precisely where the package promises never to raise.

Examples

status_message("gnomAD", "no_data")
#> [1] "No gnomAD data was found for this query."
status_message("gnomAD", "error", http = 503L)
#> [1] "gnomAD is temporarily unavailable. Please try again."

withr::with_options(
  list(biohttp.status_message = function(source, status, http, condition) {
    paste0(source, " says: ", status)
  }),
  status_message("gnomAD", "timeout")
)
#> [1] "gnomAD says: timeout"