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 problem response that describes the error and, if available, potential causes of the problem. Problems listed could include data being out of range, or specific resources not existing.

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 the problematic request and resubmit the request to the API. 

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 problems 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 become 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.

Problem Response Format

When possible, the API will reply with a problemResponse object, which is based on a shared apiProblem  object. The problemResponse object has a media type of application/problem+json and follows the RFC 9457 – 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 refers to the API resource where the problem occurred.

title is a brief description of the problem, while detail is a detailed explanation of  the specific problem.

type is a URI that can be accessed to get more information, including potential remediation steps, on the problem 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.
Refer to at Error Types for some common errors.

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

If there were multiple problems with the request, the problems will be listed in the problems array; elements of that array are also apiProblem objects.  If additional information is available for the specific problems, that information is available in the attributes object of each apiProblem object.