The Aluma.io service defines a number of RFC 7807-compliant responses, documented here on a per-API basis. In line with that RFC, the following fields are defined:

Field

Description

type

A URI identifying the type of the problem. This is a link to this documentation describing the problem type in detail. Use this as the canonical identifier of the problem type.

title

A human-readable summary of the problem type. Advisory only; do not use this to identify the problem type.

status

The HTTP status code generated for this occurrence of the problem. In practice, the value of this field will be 400 (Bad Request) or 422 (Unprocessable Entity). Advisory only, in case the HTTP status code returned is modified by an intermediary or cache.

instance

A URI reference identifying the specific instance of the problem. Unlike type, the URI does not resolve, but it can be used when contacting support to help us help you more quickly.

The classifier, documents, and OAuth access token APIs all return an alternative legacy error response format, which is not compliant with RFC 7807. The format of these responses is as follows:

{
  "message": "Validation failed",
  "requestErrors" {
    "a": [
      "The field is required"
    ],
    "b": [
      "The field must be greater than 0"
    ],
    // ...
  }
}

Field

Description

message

A human-readable summary of the problem and identifier of the problem type.

requestErrors

An object describing the validation errors raised by the request. Each field in error is a property name on the object, and the value of the property is a collection of validation messages associated with the field. In practice, few APIs include this property.

We will be migrating these APIs to the RFC 7807-compliant format over time, so an appropriate approach to parsing and interpreting errors is as follows:

  1. attempt to parse the response as an RFC 7807 Problem Details object
    a. if successful, handle the response in line with the description above.
  2. attempt to parse the response as a legacy error response object.