redcapError: Handle Errors from the REDCap API

In redcapAPI: Interface to 'REDCap'

Handle Errors from the REDCap API

Description

Determine the proper way to handle errors returned from the API. Not all errors should be fatal. See Details for more

Usage

redcapError(x, error_handling)

Arguments

x	Object returned by httr::POST().
error_handling	character(1). One of c("error", "null"). An option for how to handle errors returned by the API. see redcapError().

Details

Maintaining consistent functionality for all types of REDCap projects requires that errors be handled delicately. It is not always desirable for an error from the API to terminate the program. One example of such a case is when a user executes the exportEvents function for a classic project; doing so returns an error from the API that events cannot be exported for classic projects. In REDCap versions earlier than 6.5.0, there is no way to determine if a project is classic or longitudinal without attempting to export the events.

For this reason, it is often preferable to have these kinds of errors return NULL so that the program does not crash if it does not need to (one such instance where it does not need to crash is when exportEvents is called within exportRecords; the events argument is irrelevant to a classic project and the error can safely be ignored.

The other common type of error that does not need to be fatal is when a redcapAPI method is sent to a REDCap instance that does not support the method. For example, the exportVersion method is not supported in REDCap instances earlier than 6.0.0. In these cases, we may prefer not to cast a hard error.

These two types of errors may be handled in one of two ways. When the error handler is set to "null", a NULL is returned. When the error handler is set to "error", the error is returned. The option is set globally using options(redcap_error_handler = "null") and is set to "null" by default.

redcapAPI documentation built on Sept. 13, 2023, 1:07 a.m.