Announcement: You can find the guides for Commerce 7.5 and later on the new Elastic Path Documentation site. This Developer Center contains the guides for Commerce 6.13.0 through 7.4.1.Visit new site

This version of Elastic Path Commerce is no longer supported or maintained. To upgrade to the latest version, contact your Elastic Path representative.

Structured Messages

Structured Messages

Overview

Structured messages are returned in the messages array in a Cortex response and are used to communicate the following types of conditions:

Condition Request Methods HTTP Response Status Code
Input validation errors POST, PUT 400 Bad Request
Business state errors POST, PUT, DELETE 409 Conflict
Blocking conditions

GET
POST

200 OK
409 Conflict
Informational messages GET 200 OK

See Types of Structured Messages for further information and examples.

The messages currently returned by Cortex are listed on the following pages:

Message Fields

A structured message has the following fields:

Field / Object Description Example
type The type of the message. See Types of Structured Messages. 
"type": "error"
id A unique identifier for the message condition. 
"id": "field.required"
debug-message A text description of the error as a debugging convenience. 
"debug-message": "given-name is required"
data

A set of name/value pairs to convey message-specific data. 

"data": {
   "field-name": "given-name"
}
blocks (optional) The action that is blocked by the message condition. 
"blocks": {
   "rel": "submitorderaction"
}
linked-to (optional) A resource for users to act upon to resolve the condition. 
"linked-to": {
   "uri": "/commerce-legacy/orders/{scope}/{id}/emailinfo",
   "href": "https://{host}/{context}/orders/...",
   "type": "controls.info"
}

Example

Here is an example the messages returned when attempting to register a new account with an invalid password and email address.

400 Bad Request

{
  "links": [],
  "messages": [
    {
      "type": "error",
      "id": "field.invalid.size",
      "debug-message": "Password must be between 8 to 255 characters inclusive",
      "data": {
        "field-name": "password",
        "min": "8",
        "max": "255"
      }
    },
    {
      "type": "error",
      "id": "field.invalid.email.format",
      "debug-message": "not a well-formed email address",
      "data": {
        "field-name": "email",
        "invalid-value": "bar"
      }
    }
  ],
  "entity": {}
}