Error Responses

Summary

Errors can happen for various different reasons and in this article we'll look at the structure of error responses...

Error Structure

No matter the cause of an error, the structure of the response will always be the same.

The API will return a JSON Object with properties that describe what went wrong as well as information on how to find out more information. Here's a sample error letting us know validation has failed for the Name property:

{
  "error": {
    "code": "YM1000",
    "reference": "https://developer.youmanage.co.uk/api/errors/ym1000",
    "target": "Validation",
    "message": "Validation failed",
    "details": [
      {
        "code": "YM1006",
        "reference": "https://developer.youmanage.co.uk/api/errors/ym1006",
        "target": "Name",
        "message": "'Name' must not be empty.",
        "details": null
      }
    ]
  }
}

The response contains an object with a single property error which, along with the HTTP status code, you can test to determine if the request has failed. The error object will contain the actual information about the problem encountered.

In our example, we can see from the target and message properties that we are dealing with a validation problem. The target property tells us which part of our request the error object is describing and the message property gives a human-readable description of what the problem was. Each error will also contain a unique code and a link to the documentation which will describe the error in more detail and give examples of what went wrong and how to fix them.

The final property on the error object is the details property. This property allows each error object to contain an array of child error objects, which still adhere to the same format as the parent error object but describe the error at a more granular level. In this example, we can see the details property contains an array with a single child error response which, from the target and message properties, tell us that the request needs to send a property Name and that it must have a value.

Now that we've covered error responses we'll take a look at validation errors, which although similar to errors contain some key differences.