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 code	Definition
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 property	Definition
`type`	string._ The type of error encountered - see error types below for a list of possible types.
`message`	string._ A description of the error.
`more_info`	string._ 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 type	Description
`validation_error`	Indicates that the request is invalid due to a validation error. Usually accompanied by a 400 HTTP status.
`invalid_request_error`	Indicates that the API cannot fulfill the request. Usually accompanied by a 400 HTTP status.
`not_found_error`	Indicates that either the URL doesn't exist, or the requested resource can't be found. Usually accompanied by a 404 HTTP status.
`authentication_error`	Indicates that the request could not be successfully authenticated (missing or invalid credentials). Usually accompanied by a 401 HTTP status.
`authorization_error`	Indicates 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_error`	Indicates that you've made too many requests in a short space of time. Usually accompanied by a 429 HTTP status.
`api_error`	Indicates a server error during the request. Usually accompanied by a 500 HTTP status.
`conflict_error`	Indicates a conflict on the server in the current resource's state.

Sub-error object

Property	Definition
`path`	string._ The path to the field in the request payload.
`message`	string._ A description of the error.