Handling Errors

Overview

When requests to API resources fail, the system will adhere to the following conventions to communicate the type of failure and any possible details that might be helpful in fixing the problem. This consists of two parts: an HTTP response code indicating the error type, and a JSON response object with any availble information about the error.

HTTP Status Codes

Error responses are always indicated with an HTTP status code of 400 or above. A status in the 4xx range indicates that the system understood your request but that there was some problem with your input that prevented a normal response. Examples include 404 (not found) when requesting a specific item by id and the item no longer exists or your provided id is invalid; or 400 (bad request) when a new item is posted but fails validation (i.e. a new user’s email address is not formatted correctly).

Response fieldErrors Property

In cases where a PUT or POST request fails because of problems with a specific property on the object posted in the request, the error is described in a fieldErrors property. For example:

{
	"fieldErrors": { "name" : "This field is required." }
}

The fieldErrors property contains an object whose properties are the names of fields from the object you provided in the request, and the values are descriptions of errors that occured on the given property.

Response errors Property

In cases where your request consists of valid data but there are other reasons your request failed, those errors are described in an errors property. For example, when trying to register a user into an offering for which they are already enrolled, you may encounter this error:

{
	"errors": [ "This offering is not available for registration for the given user." ]
}

Note that the errors value is an array of strings containing descriptions of why your request failed.