Error Responses and Error Representation

The response schemas for Apiture Open Banking APIs includes HAL _links, an _embedded object, and an _error object. Thus, operations do not need to declare a separate error schema. The location for error information is built into the default base schema used by all response schemas (such as accounts, transfers, transactions, collections, etc.) If an error occurs (such as a 4xx or 5xx response code), the _error object describes the error, and other properties of the response schema may be omitted.

For example, if the client sends a request body that is invalid, they may receive a 400 response code or another more specific 400-level response code. The response body is a JSON HAL response that includes the _error object. For example, here is a possible JSON HAL response with an _error object:

{
  "_error": {
    "_id": "2eae46e1-575c-4d69-8a8f-0a7b0115a4b3",
    "_profile": "https://api.apiture.com/schemas/error/v1.0.0/profile.json",
    "message": "The value for a deposit must be greater than 0.",
    "statusCode": 422,
    "type": "positiveNumberRequired",
    "attributes": {
      "value": "-125.5",
      "name" : "deposit.value"
    },
    "remediation": "Provide a value which is greater than 0",
    "occurredAt": {},
    "_links": {
      "describedby": {
        "href": "https://developer.apiture.com/errors/positiveNumberRequired"
      }
    },
    "_embedded": {
      "errors": []
    }
  }}

The error object contains the following properties:

Property	Type	Description
`_id`	`string`	A unique identifier for this error instance. This may be used as a correlation ID with the root cause error (i.e. this ID may be logged at the source of the error). This is is an opaque string.
`message`	`string`	A message string describing the error condition.
`statusCode`	`integer`	The HTTP response code associated with this error.
`type`	`string`	An error identifier which indicates the category of error. The `type` provides a finer level of granularity than the `statusCode`. See Error Types below.
`attributes`	`object`	Additional data attributes associated with the error, such as values or constraints. See Error Attributes below.
`remediation`	`string`	An optional localized string which provides hints for how the user or client can resolve the error.
`occurredAt`	`string`	An RFC 3339 UTC time stamp indicating when the error occurred, in the format `YYYY-MM-DDYhh:mm:ss.sssZ`.
`_embedded`	`object`	An optional object that contains resources related to the error. Its optional value `errors` is an array of root cause nested error objects (HAL representations). For example, if the request input validation finds several errors in the input, each is listed in `_embedded.errors`, and the overall error response is a generic `400 Bad Request` error. This field may not exist if the error does not have nested errors.
`_links`	`object`	Links associated with the error. The `describedby` link, if present, is a link to a web page which describes the error `type` and what attributes are associated with that error type.

Error Attributes

An _error object may contain additional data about the error in the attributes property. This is an open (JSON) object.

Examples

Error Type	Attributes
`positiveNumberRequired`	- `value` which represents a non-positive number - `name` which indicates which value in the request is in error
`integerValueNotInAllowedRange`	- `value` The actual value that was submitted in the request. - `minimumValue` - `maximumValue`
`deleteApprovalConflict`	- `requiredStates` which lists the set of allowed states in which the resource must for a valid `DELETE`

Attributes vary with each type.

Error Types

Most error responses contain a type string which indicates the category of the error. The UI tier can use this value to render an appropriate message or hint. The type provides a finer level of granularity than the statusCode. For example, instead of just 400 Bad Request, the type is more specific and descriptive, such as integerValueNotInAllowedRange, numericValueExceedsMaximum, or stringValueNotInAllowedSet.