Error Handling

Error Response Payload

For some errors returning the HTTP status code is enough to convey the response. Additional error information can be supplemented in the response body. For example; HTTP 400 Bad request is considered to be too generic for a validation error and more information must be provided in the response body.

Defined here are the attributes of the error object, which may be extended to include additional attributes as required to meet specific business or enterprise requirements.

The error schema may be extended with optional fields (e.g. ‘helpUrl’) as required to meet specific business or enterprise requirements. The returned error objects must be in a collection (array) – see the examples for details.

Input Validation

There are two types of input validation errors

Error Samples

A sample 400 Bad Request error response:

{
  "errors": [
    {
      "id": "86032cbe-a804-4c3b-86ce-ec3041e3effc",
      "detail": "Invalid value(s) in request input",
      "code": "19283",
      "source": {
        "parameter": "postcode"
      }
    },
    {
      "id": "45786a8f-452e-492f-a779-801b5d0bd0a7",
      "detail": "Input value(s) exceeded maximum length",
      "code": "19284",
      "source": {
        "parameter": "last_name"
      }
    }
  ]
}

A sample 500 Internal Service error:

{
  "errors": [{
    "id": "86032cbe-a804-4c3b-86ce-ec3041e3effc",
    "detail": "Downstream system is not responding correctly"
    "code" : "500"
  }]
}

Warning and Information Responses

It may be appropriate in some scenarios for resource servers to return information about non-critical errors or other significant conditions. The necessity of any mechanism intended to convey information about a resource that is not encompassed in the canonical representation of that resource should be carefully considered. When employing extra-data messages, the intent of such messages MUST be clearly articulated in API specifications, MUST NOT constrain or direct client behaviour (i.e. avoid close coupling) and MUST NOT be stateful (i.e. do not represent retention of client state by the server). Warning and information messages SHOULD be returned only in exceptional circumstances, MUST ONLY be returned by a server and MUST NOT be passed to a server by a client.

When utilised. Warning and information messages MUST be returned as child objects of a single ‘messages’ top level collection, and MAY ONLY be returned with a success response (Success 200, 201), Bad Request (400) or Unprocessable Entity (422).

The messages object MUST conform to the error object definition described above, and SHOULD include an aditional ‘severity’ attribute.

Sample warning content :

{
  "data": {
    "applicationId": "65648987234",
    "creationDate": "2020-01-01",
    "applicantId": "123456",
    "status": "incomplete"
  }
  "messages": [
    {
      "severity": "warning",
      "id": "86032cbe-a804-4c3b-86ce-ec3041e3effc",
      "code": "APP0025",
      "detail": "application 65648987234 to be retired 2022-01-01 due to inactivity"
    }
  ]
}