API Errors

The API will return all errors as JSON objects with a message property and optionally an errors array. The format is the same as that described by JSON API.

#Examples

Here are some common error messages that you might encounter.

#Signature Errors

Status code: 400

If you are creating your own client for the Integration or Management API, you will need to implement the request signing algorithm detailed in the Integration API Authentication or Management API Authentication references.

{
  "message": "HMAC signature mismatch."
}

#Validation Errors

Status code: 400

By far the most common error is validation errors of request payloads or parameters.

If you send a customer profile update with an unknown profile attribute MyCoolAttribute, you would receive the following response:

{
  "message": "The submitted data was invalid",
  "errors": [
    {
      "title": "Unknown",
      "details": "The attribute \"MyCoolAttribute\" is not defined on CustomerSession entities.",
      "source": {
        "pointer": "/attributes/MyCoolAttribute"
      }
    }
  ]
}

The source.pointer property of the first argument is a JSON pointer to the invalid data in the payload.

If you send the wrong data type for an attribute, you would receive a similar response:

{
  "message": "The submitted data was invalid",
  "errors": [
    {
      "title": "Invalid type",
      "details": "Value of \"Name\" attribute (false) is not a string",
      "source": {
        "pointer": "/attributes/Name"
      }
    }
  ]
}

Or sending an invalid state in a customer session update:

{
  "message": "The submitted data was invalid",
  "errors": [
    {
      "title": "enum",
      "details": "state must be one of the following: \"open\", \"closed\", \"cancelled\"",
      "source": {
        "pointer": "/state"
      }
    }
  ]
}

In any validation error related to a request payload, you should always look first to the source.payload pointer and then the details to determine how to resolve the issue.