Error Responses and Error Representation

This page describes how errors are represented when an error occurs in an API call.

The response schemas for Apiture APIs extends from an abstract response schema which includes HAL _links and _embedded object and also 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 will describe the error with additional properties, and other properties of the expected 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 other more specific 4xx 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 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
message string A message string describing the error condition.
_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.
statusCode integer The HTTP status code associate 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 Optional object that may contains resources related to the error. The optional value errors is an array of root cause nested error objects (HAL representations). For example, if request input validation finds several errors in the input, each will be listed in _embedded.errors, and the overall error response will be 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

  • In an error with the type of positiveNumberRequried, the attributes contains a property value which represents a non-positive number and a name property which indicates which value in the request is in error.
  • The attributes for an integerValueNotInAllowedRange contains value (the actual value that was submitted in the request) and minimumValue and maximumValue.
  • For the deleteApprovalConflict error type, the requiredStates attribute lists the set of allowed states the resource must be in order for a DELETE operation to be valid.

Attributes vary with each type and are described for each error as documented in Error Types below.

Error Types

Most error responses contain a type string which indicates the category of 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 may be much more specific, such as integerValueNotInAllowedRange or numericValueExceedsMaximum or stringValueNotInAllowedSet.

Additional documentation for errors may be found in the errors section of the API reference documentation on the developer portal. The error representation will include a link with the standard IANA describedby link relation. The link will be a human-readable web page (HTML) containing information about that specific error, including a description of the attributes associated with that error type.

For example, additional documentation about the error type deleteApprovalConflict is found at https://developer.apiture.com/errors/deleteApprovalConflict. (Note: Such URLs may redirect to other locations.)