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 receive.

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 MyAttribute, you receive the an error object with the following structure:

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

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 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, look first to the source.payload pointer and the details to determine the issue.