Error Responses and Error Representation

The response schemas for Apiture Open 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.