Error Responses (4xx / 5xx)

In the event that a request to the API results in an error, the API will attempt to respond with an HTTP status code and response body, which describes what went wrong.

Status Codes

HTTP status codes returned by the API will conform to the standard codes set forth by IETF, e.g. “401” for Unauthorized, “404" for Not Found, “422” for Unprocessable, etc. Wikipedia is a handy place to find a comprehensive list of HTTP status codes.

Error Response Body

When the API responds with an error status code, the response body will contain a JSON-formatted list of errors that describe the thing(s) that went wrong when the API tried to process the request. In most cases, there will be only one error, but in cases like API endpoints that process data in batch, there may be multiple errors. This list of errors is never paginated.

All error objects will have a code and a detail attribute. The code attribute describes the type of error that occurred, and it provides an indication of the other properties that may exist on that error object to aid programmatic processing of the error. The API will return one of two types of errors: a ‘general’ error or a ‘validation’ error.

{
      “errors”: [
        {
          “code”: “general”,
          “detail”: “Could not create a new user record.”
        },
        {
          “code”: “validation”,
          “attribute”: “email_address”,
          “detail”: “A user’s email address cannot be blank.”
        }
      ]
  }

General Errors

A General error suggests that error occurred for a reason not related to data that was passed for update or creation, but rather a reason related to the request itself, like authentication or database record retrieval. Most errors that the API returns will be General errors.

The attributes of a general error are:

{
      “errors”: [
        {
          “code”: “general”,
          “detail”: “Missing X-Api-Key header”
        }
      ]
  }

Validation Errors

A Validation error suggests that a property or attribute of an object passed to the API is invalid, due to data type, formatting, or enumeration reasons. These errors are designed to support in-line error messaging in the html forms of an application built on the API. A validation error will often, but not always, be accompanied by a General error. A Validation error will always have an attribute attribute, which a General error does not.

The attributes of a Validation error are:

{
      “errors”: [
        {
          “code”: “validation”,
          “attribute”: “field_id”
          “detail”: “The field id must be numeric.”
        }
      ]
  }