Error Responses and Error Representation

Warning The Apiture Open product line will reach end of life December, 2023. Consumers of the Apiture Open APIs should migrate to the Apiture Digital Banking APIs before that time.


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

HTTP Response Codes

See HTTP for API Transport for more details about HTTP error response codes (4xx and 5xx response codes.

The API definitions list the most common HTTP response codes for each operation, but those lists are not comprehensive.

For example:

  • All operations may return a 401 Unauthorized if the API Key is omitted in the request or if the Authorization header is omitted for operations which have a oauth2 security requirement.
  • All operations may return a 403 Forbidden.
  • All operations which reference resources (normally through path parameters) may return 404 Not Found, 410 Gone, or 403 Forbidden.
  • All operations which accept a request body, query parameters, or header parameters my return 400 Bad Request or 422 Unprocessable Entity.
  • The API services may return 405 Method Not Allowed, 406 Not Acceptable for incorrect API calls (wrong HTTP method or wrong Accept header, respectively)
  • All clients should be prepared for any operation to return 429 Too Many Requests and throttle their call rates accordingly.

Clients should be robust enough to handle any valid HTTP response code, including 3xx response codes, not just those defined in the OpenAPI definitions.