Errors

The majority of errors will be returned in the JSON Specification error format. Runtime errors which are unhandled may not be formatted correctly.

Older services may return mixed error structures. The technical_error field may not always be available. This is a field for internal use only and not intended to be consumed by the public site so is usually removed. In most cases, any known error will return a standard error structure as described. The data.errors key can have 2 different formats, depending on the error status.

For 422 statuses, this will be an array of arrays, with the name of the field which failed validation being the key:

For non 422 errors, the errors array may contain a basic array<string> style.

Some older services will return errors in a semi-unstructured format. For example, the response may only contain a single errors key.

Status codes

We use HTTP status codes to indicate whether the response was successful or not, and whether it was a client based issue or an internal error.

We'll never return a successful response for an error state.

Name
2xx
Required
Type
Description
A 2xx status code indicates a successful response and that the request was handled correctly.
Name
4xx
Required
Type
Description
A 4xx status indicates an error that was caused by the client. 4xx errors generally indicate the user may try again, with different inputs which may resolve the issue.
Name
5xx
Required
Type
Description
A 5xx status indicates an internal service issue. These errors cannot be resolved by the user.

Error Resources

We try to stick with a version of the JSON API error response wherever possible. All errors should be structured the same, with the exception of some legacy projects, and runtime errors which might not be handled.

Name
id
Required
Type
string
Description
This is the unique ID of this particular error. If this same error occurs on another request, the ID will be different. It is intended to be used to help track down specific user reported errors in our error tracking tooling.
Name
status
Required
Type
integer
Description
This will usually be the HTTP status that was returned with the error.
Name
code
Required
Type
string
Description
A short, user friendly code to track down the type of error. For example, if a user cannot be found, the code might be user_not_found.
Name
title
Required
Type
string
Description
A friendly title for the error which should be displayed to the user.
Name
details
Required
Type
string
Description
A brief explanation about the error, and what the user may try, to resolve the error. This should be displayed to the user.
Name
errors
Required
Type
array
Description
An array of error messages. Depending on whether this is a validation based error, or generic error will determine the structure of this array. For validation based errors (422 statuses), this will be an array of string arrays (See below for example). For general errors, this will just contain an array of error messages or hints.
Name
meta
Required
Type
array<string>
Description
An array of generic key-value dictionary of error data. For internal, local, development and test requests, there will be a technical_error key which will provide internal details about the error. This key is removed in production environments to prevent it being accidently leaked to the user.

Standard Error Response

{
  "id": "0effe54c-1aeb-4d3b-8d0f-5eb3b9bdd41d",
  "status": 400,
  "code": "internal_error",
  "title": "An error occurred",
  "details": "There was an error while trying to process your request. Please try again.",
  "errors": [
    "The user account is locked and may not be used for this request."
  ],
  "meta": {
    "technical_error": "The database was unavailable",
  }
}

Validation Error Response

{
  "id": "0effe54c-1aeb-4d3b-8d0f-5eb3b9bdd41d",
  "status": 422,
  "code": "create_user_validation",
  "title": "An error occurred",
  "details": "Please review the form errors.",
  "errors": [
    "first_name": [
      "The first name is required",
      "The first name must be at least 2 characters"
    ]
  ],
  "meta": {
      "technical_error": "Validation errors",
  }
}