Responses and Errors

This page contains the following sections:

• Response Status Codes
• Responses
• Error Message Structure
  • RFC 7807
  • Error Message Standards

Response Status Codes

HTTP response status code are defined according to section 6 of RFC7231.

The following table summarizes a simplified response codes list used in Open APIs:

Responses

Responses can be expressed in various ways in the OpenAPI specification e.g. adding the details at each end point or leveraging the data structure of the response body. The preferred way and the most reusable way is to leverage the dedicated response section:

Not recommended:

path: 
/customers/{customerId}':
    get:
      parameters:
        type: 
        - $ref: '#/parameters/customerId'
      operationId: get-customers-customerId
      responses:
        '200':
          description: This API retrieves the party details.
          schema:
            type: object
            properties:
              name:
                type: string

Recommended - to allow reusability, consistency and reduce maintenance - especially for a common error pattern:

path: 
/customers/{customerId}':
    get:
      tags:
        - Party
      parameters:
        - $ref: '#/parameters/partyId'
        - $ref: '#/parameters/X-Request-ID'
      summary: Read party.
      description: Read party.
      operationId: get-parties-partyId
      responses:
        '500':
          $ref: '#/responses/500_INTERNAL_ERROR'

responses:
   '500_INTERNAL_ERROR':
    description: Internal Server Error.
    schema:
      $ref: '#/definitions/Error'

The following table lists rules for response codes:

Error Message Structure

This section includes the following:

• details of RFC 7807 - this is the basis of error message structure
• details of standards relating to error messages

RFC 7807

RFC 7807 provides a standard format for returning problem details from HTTP APIs.

RFC7807 proposes a structure for common pattern of errors whilst also allowing for extensions. The following text is taken from RFC7807 and describes the principal fields of the error message structure that APIs adopt:

• type (string) - A URI reference [RFC3986] that identifies the problem type. This specification encourages that, when dereferenced, it provides human-readable documentation for the problem type, using, for example, HTML ([W3C.REC-html5-20141028]). When this member is not present, its value is assumed to be about:blank.
• title (string) - A short, human-readable summary of the problem type. It SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization using, for example, proactive content negotiation - see [RFC7231], Section 3.4).
• status (number) - The HTTP response status code ([RFC7231], Section 6) generated by the origin server for this occurrence of the problem.
• details (string) - A human-readable explanation specific to this occurrence of the problem.

Error Message Standards

The following are the Open API error message standards:

The standard error message structure is as follows:

{
    "type": "https://api.finastra.com/validation-error",
    "title": "The request could not be processed due to applicable business validation",
    "status": 400,
    "detail": "Ensure that the request is valid"
}

If additional details of one or more error messages are needed then an array of causes can be provided, however, the presence and structure of causes is not mandated.

The following example shows how causes might be used:

{
  "type": "https://api.finastra.com/validation-error",
  "title": "The request is invalid",
  "status": 400,
  "detail": "The account does not exist",
  "causes": [
    {
      "title": "The account '1234567890' is dormant",
      "field": "account",
      "fieldValue": "0543123467083"
    }
  ]
}