Errors

Overview

In the event that a request fails, the Root API will provide you with as much information as possible to help you find a solution.

HTTP status codes

We use standard HTTP status codes to indicate whether a request succeeded or failed. To keep things predictable, we've limited the codes in use to the following:

HTTP codeDefinition
200 (OK)The request was successful.
400 (Bad Request)The request was unsuccessful, usually due to incorrect parameters.
401 (Unauthorized)The request could not be authenticated, usually due to missing or incorrect auth credentials in the request.
403 (Forbidden)The request was authenticated, but you do not have permission to perform the request.
404 (Not Found)Either the URL doesn't exist, or the requested resource was not found.
409 (Conflict)The request could not be processed because of conflict in the current state of the resource, such as an edit conflict between multiple simultaneous updates.
429 (Rate Limit)You've made too many requests in a short space of time - wait a few minutes and try again.
500 (Server Error)Something went wrong in the Root API - these are rare.

Error object

In addition to the HTTP status code, the response payload will include more details on the actual error. Error responses contain a top-level error key in the payload, which will hold a standardised error object as follows:

Error object propertyDefinition
typestring. The type of error encountered - see error types below for a list of possible types.
messagestring. A description of the error.
more_infostring. A link to this error documentation, to help debug the error.
trace_id
optional
string. A unique error ID used by Root to track and resolve the error. This will usually only be included in server errors.
errors
optional
array. A list of sub-error objects, usually used to indicate specific fields that failed validation. See sub-error object below for the format.

Error types

Error typeDescription
validation_errorIndicates that the request is invalid due to a validation error. Usually accompanied by a 400 HTTP status.
invalid_request_errorIndicates that the API cannot fulfill the request. Usually accompanied by a 400 HTTP status.
not_found_errorIndicates that either the URL doesn't exist, or the requested resource can't be found. Usually accompanied by a 404 HTTP status.
authentication_errorIndicates that the request could not be successfully authenticated (missing or invalid credentials). Usually accompanied by a 401 HTTP status.
authorization_errorIndicates that the request could not be successfully authorized (missing permission or role to perform the request). Usually accompanied by a 403 HTTP status.
rate_limit_errorIndicates that you've made too many requests in a short space of time. Usually accompanied by a 429 HTTP status.
api_errorIndicates a server error during the request. Usually accompanied by a 500 HTTP status.
conflict_errorIndicates a conflict on the server in the current resource's state.

Sub-error object

PropertyDefinition
pathstring. The path to the field in the request payload.
messagestring. A description of the error.