Error handling

Learn how to recognise and handle errors.


The error reporting differs between our v2 and v3 services. You must ensure you use the correct method for the call in use. Learn how to identify which API version a call uses here.

With the Dotdigital API, you can expect 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: a request parameter wasn't included, an object couldn't be found, etc.
  • 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.

For v3 service calls

For API v3 calls and higher we provide more error information in the form of a standard error response. The error response contains both 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:

errorCodestringYesUnique code per error raised by the service.
descriptionstringYesUseful description of the error in American English.
detailsarray of error objectNoOptional array of error details, such as a list of bad parameters.

error object:

itemstringYesThe item the error is associated with, for example, field name, unique identifier for an entity, or item in batch.
descriptionstringYesUseful 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"

What’s Next