redcap_error: Handle Errors from the REDCap API

Description Usage Arguments Details Handled Errors Author(s)

View source: R/redcap_error.R


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


redcap_error(x, error_handling)



Object returned by POST.


Direction for how to handle errors. May be either "null" or "error". See 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 doesn't crash if it doesn't need to (one such instance where it doesn't 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.

Handled Errors

Only the errors listed below are handled. All others throw a hard error.

"ERROR: The value of the parameter \"content\" is not valid"
"ERROR: You cannot export arms for classic projects"
"ERROR: You cannot export events for classic projects"


Benjamin Nutter

redcapAPI documentation built on Feb. 18, 2020, 1:09 a.m.