Errors

All API calls use a standardized format for returning errors. The simplest way to explain it is by example:

{
    "errors": [
        {
            "properties": [
                "firstName"
            ],
            "text": "First name may not contain numbers",
            "code": "INVALID_PARAMETER"
        }
    ]
}

The errors key will always contain an array of objects, even if there is only one error. Each error object always contains a code, which is a terse machine-readable code for what went wrong (think of it as an enum), a text value, which is a long-form description suitable for display to end users, and optionally a properties array which contains the keys that were invalid in the request. If there are multiple values in the properties array, then the error is caused by the combination of the two, e.g. a city name that doesn’t match a submitted postal code. In the above example, the API consumer attempted to POST an invalid value of firstName to the /contacts API.

If an API call does not return an errors array, then the call was successful, and the specific return data varies per call.