Error handling

The API uses conventional HTTP response codes to indicate the success or failure of an API request.

Typically, HTTP response codes mean:

200 range - a successful request
400 range - a failed request: for example, a request parameter wasn't included, an object couldn't be found.
500 range - an error with our servers: these are rare.

400 range HTTP response codes indicating a failed request come with an error response type in the body of the response.

The error response

The error response contains both a machine-readable version of the error as well as human readable (in American English) to ensure the errors can be reliably understood and handled by code as well as give good quality error feedback to the developer.

The error response data contract is:

Field	Type	Mandatory	Notes
errorCode	string	Yes	Unique code per error raised by the service.
description	string	Yes	Useful description of the error in American English.
details	array of error object	No	Optional array of error details, such as a list of bad parameters.

error object:

Field	Type	Mandatory		Notes
item	string	Yes		The item the error is associated with, for example, field name, unique identifier for an entity, or item in batch.
description	string	Yes		Useful description of the error in American English.

For example:

Basic error:

{
  "errorCode": "accounts:maxAccountLimit",
  "description": "Maximum account limit reached!",
}

Using the details array:

{
  "errorCode": "contacts:invalidContacts",
  "description": "Invalid contact data",
  "details": [
    {
      "item": "email",
      "error": "You must specify a value"
    },
    {
      "item": "firstName",
      "error": "Cannot exceed 256 characters"
    }
  ]
}