Log In / Register

Error Responses

When an error occur, the Apiture API attempts to provide as much information about the issue as possible. The API responds with an HTTP response code and with a JSON response body. The JSON response body is an error response that describes the error and, if available, potential causes of the error.

Some errors are caused by issues in the request. The request may have been made to an invalid URI, the request may be improperly formatted, there may be invalid data in the request, and many other potential causes. Issues with the request will receive a 400-level error status response. The submitter of the request can fix it and resubmit the request to the API. The corrected request should work as expected.

Other errors are caused by issues with the API. The service may be down for maintenance, a database may be inaccessible, or other problems with availability.  Issues with availability will receive a 500-level error status response. These are not problems with the request, and the client will need to wait for the service to be made available again.

API operations may return any valid HTTP response code to indicate 4xx or 5xx errors. The API reference documentation lists the most common errors, but does not exhaustively list all HTTP errors on every operation.

Error Format

When possible, the API will reply with a problemResponse object. The problemResponse object has a media type of application/problem+json and follows the RFC 7807 – Problem Details for HTTP APIs schema with several additional fields for further information.

An example is available below:

{
  "id": "3fbad566-be86-4b22-9ba6-3ca99fdc0799",
  "type": "https://api.apiture.com/errors/noSuchAccount/v1.0.0",
  "title": "Account Not Found",
  "status": 422,
  "occurredAt": "2022-04-25T12:42:21.375Z",
  "detail": "No account exists for the given account reference",
  "instance": "https://api.apiture.com/banking/transfers/bb709151-575041fcd617"
}

Each instance of an error is assigned a unique problemResponse id. The id is stored in the API’s backend error logs so it can be referenced, if needed, during troubleshooting. instance references where the error occurred, although the instance reference id will not match the problemResponse id.

title is a brief description of the error, while detail is a longer explanation of what the error means.

type is a URI that can be accessed to get more information, including potential remediation steps, on the error that occurred. In the type, the error type name is visible after the /error/ in the URI. In the example above, the error type name is noSuchAccount. This is not the same as title. The error type name can be used to find more information in the API Documentation, if necessary. Error type is documented further on our concepts page.

The time when the error occurred is stored in the occurredAt field. status is the HTTP error code associated with the issue.

If there was an identifiable problem with the request, the problems will be listed in the problems array. Problems listed could include data being out of range, or unique resources not existing. If additional information is available for the specific errors encountered, that information is available in the attributes object.