REDCap API Error Codes

Each API request returns a status message. The list of possible status codes is given below, although the exact message may vary depending on what error occurred. In the redcapAPI package, only the numeric portion of the status code is returned to the user. For instance, if an attempt was made to export data from a project in which the user does not have API permissions, the user would see the message '403: You do not have permissions to use the API'--the 'Forbidden' tag is left off the message.

In cases where the call runs successfully, no message is returned to the user.

Status Codes

The REDCap API attempts to return appropriate HTTP status codes for every request.

200 OK: Success!

400 Bad Request: The request was invalid. An accompanying message will explain why.

401 Unauthorized: API token was missing or incorrect.

403 Forbidden: You do not have permissions to use the API.

404 Not Found: The URI you requested is invalid or the resource does not exist.

406 Not Acceptable: The data being imported was formatted incorrectly.

500 Internal Server Error: The server encountered an error processing your request.

501 Not Implemented: The requested method is not implemented.

(REDCap API Documentation)

Boring detail warning: The importFiles and deleteFiles behave slightly differently in that the content returned after a successful call is incompatible with the structure the httr package expects. As a result, if an error is thrown during the httr::POST call, the redcapAPI package assumes the action was successfully completed--the error is caught and an alternate message is displayed. If no error is thrown during the httr::POST call, that means the action was unsuccessful and the error code from the API is returned and displayed.

Supplemental API Messages

In addition to the status code, the API will also return a message describing the error. When the status code is 200 (success), no message is returned by the redcapAPI package. Other messages you may encounter are listed below with a brief explanation.

Note: these are error messages that I have encountered while developing the redcapAPI package. This list may not include every message you might encounter, but I have tried to minimize the number of errors returned by the API. Instead, I try to return errors from R before making calls to the API

Could not resolve host: [URL]; Host not found: Technically, this is not a REDCap API message, but is returned by httr::POST when the url provided by redcapConnection cannot be found.
The value of the parameter "content" is not valid: Since the content parameter is strictly controlled by the redcapAPI package and cannot be altered by the user, this error can only mean that the requested function does not exist in your version of REDCap.
You cannot export arms for classic projects: Your project is not a longitudinal project. Rather than returning an error in R, this message returns as a character string. This prevents fatal errors from being thrown when working with classic projects.
You cannot export form-event mappings for classic projects: Your project is not a longitudinal project. Rather than returning an error in R, this message returns as a character string. This prevents fatal errors from being thrown when working with classic projects.
You cannot export events for classic projects: Your project is not a longitudinal project. Rather than returning an error in R, this message returns as a character string. This prevents fatal errors from being thrown when working with classic projects.
You do not have permissions to use the API: Although you have access to the project, your user rights profile does not give you API access. Note that even if you have export privileges, you may receive this message if you try to import without import privileges (or vice versa)
You do not have API data import/change/delete rights: You have not been authorized for API import. It is possible to receive this error even though you have API export rights.