Build a result envelope — envelope • biohttp

The single return shape for the whole package. ok is derived from status rather than passed in, so the two can never disagree.

Usage

envelope(
  status,
  data = NULL,
  source = "API",
  http = NA_integer_,
  error = NULL,
  detail = NULL,
  retry_after = NA_real_
)

Arguments

status: One of STATUS_LEVELS.
data: The parsed body on success, NULL otherwise.
source: A friendly label for the service, used in the user-facing message. For example "gnomAD".
http: The HTTP status code, or NA_integer_ when no response arrived.
error: One sentence fit to show a user. Never carries technical detail.
detail: The technical cause, for a log. Never shown to a user.
retry_after: Seconds a Retry-After header asked the caller to wait, or NA_real_ when the response carried none. Diagnostic: nothing in this package reads it back except the batched retry path in parallel.R, which shares this same field.

Value

A list with ok, status, http, data, source, error, detail, retry_after, and ts.

Details

A client that only wants the parsed body can use body_or_null() instead of reading the fields directly.

Examples

envelope("ok", data = list(symbol = "BRCA1"), source = "MyGene", http = 200L)
#> $ok
#> [1] TRUE
#> 
#> $status
#> [1] "ok"
#> 
#> $http
#> [1] 200
#> 
#> $data
#> $data$symbol
#> [1] "BRCA1"
#> 
#> 
#> $source
#> [1] "MyGene"
#> 
#> $error
#> NULL
#> 
#> $detail
#> NULL
#> 
#> $retry_after
#> [1] NA
#> 
#> $ts
#> [1] "2026-09-16 15:01:37 UTC"
#> 
envelope("error", source = "gnomAD", http = 503L)
#> $ok
#> [1] FALSE
#> 
#> $status
#> [1] "error"
#> 
#> $http
#> [1] 503
#> 
#> $data
#> NULL
#> 
#> $source
#> [1] "gnomAD"
#> 
#> $error
#> NULL
#> 
#> $detail
#> NULL
#> 
#> $retry_after
#> [1] NA
#> 
#> $ts
#> [1] "2026-09-16 15:01:37 UTC"
#>