Error Handling

There are multiple points where an error may occur to prevent booking and referral operations from completing successfully. This section provides error handling guidance for BaRS and its associated API. For More Detail on error handling, there is specific information on failure scenarios available in the section in addition to information included on this page.

Overview

Error codes (HTTP Response codes) can be caused by any of the three parties involved in a transaction using the Booking and Referral API. Error codes will be accompanied by a OperationOutcome FHIR resource where possible. Error codes and their relative operation outcome codes are meant for developer use only - they should not be presented to end-users. Instead, sending applications should interpret the two codes and provide user-friendly resolution steps on failure. Sender and receiver systems should record the detailed error codes in local logs in order to support service incident investigation. There are scenarios where an operation outcome may not be applicable or available. A HTTP Response code should always be returned.

Operation Outcome Codes are prefixed with an indicator of the source of the error help identify where a problem may be.

The following table provides a high-level overview of each stage in the booking and referral process from the perspective of a sending application.

BaRS interactions (sending)

In the event of an error; the BaRS API always responds with an HTTP response code (issue.code) and an OperationOutcome code (issue.details.code) within an OperationOutcome FHIR Resource - conditioned on it being reached successfully. Assuming the sender's access token (obtained from the Oauth 2 endpoint) is accepted and the request is valid, the BaRS API processes the request. Depending on the operation, BaRS proxies the request to the receiver. Depending on where in this flow the error occurs, the OperationOutcome codes is prefixed with one of the following three items, indicating where the cause of the error resides:

• SEND - The sending application is the cause of the error
  • These items are only be generated by the API to indicate there was an issue with the senders request
• PROXY - The BaRS Service is the source of the error
  • These items generally generated to indicate there was an error internal to BaRS
  • The information within the response will help identify the cause
• REC - The receiver is the source of the error
  • These are generated by the receiver, however if there is a scenario where the receiver cannot respond, these are generated by the proxy to clarify the source of the problem
  • The information within the response helps identify the cause

These OperationOutcome codes are part of a value set to be used within a OperationOutcome FHIR Resource (issue.details.code) which forms the body of the response. Below is an example of an error response:

OperationOutcome Example

  "resourceType": "OperationOutcome",

  "id": "4e2e13af-3bc7-4de3-8cc5-ea4f14d45ef8",

  "meta": {

    "profile": [

      "https://fhir.hl7.org.uk/StructureDefinition/UKCore-OperationOutcome"

    ]

  },

  "issue": [

    {

      "severity": "error",

      "code": "invalid",

      "details": {

        "coding": [

          {

            "system": "https://fhir.nhs.uk/CodeSystem/http-error-codes",

            "code": "PROXY_BAD_REQUEST",

            "display": "400 - PROXY_BAD_REQUEST"

          }

        ]

      },

      "diagnostics": "BaRS encountered a conflict: <further diagnostics information, error message/error text>"

    }

  ]

}

Diagnostics text

The purpose of the two code values are to give high level information as to the nature and source of an error response. The diagnostics text is to contain clear and concise information regarding the exact cause of the problem encountered, where possible. This should include information on the problem encountered, internal debug details such as error message and texts are encouraged, exposing stack traces is not. The diagnostics field does not include any patient identifiable information at any time.

Example errors

The table below contains some further examples of error codes, their associated Operation Outcomes codes and and potential diagnostics texts.

Sender responsibilities

• Log errors returned for incident investigation by IT support staff
• Ensure sufficient information for appropriate local incident management is captured
• Communicate with receivers should an unexpected error be received consistently (REC)
• Communicate with NHS Digital should a persistent error state be encountered from BaRS (PROXY)
• Inform end-user with a suitable message appropriate to the business flow, for example: critical error with advice to call local IT helpdesk, or business process options to warn users to choose another service

BaRS interactions (receiving)

Receiver responsibilities

• Receiving APIs should adhere to the HTTP Response code and Operational Outcome code paradigm described above in the event that an error response needs to be returned
• The sender should be able to ascertain what went wrong and why in the event of an error
• Receiving endpoints should use the REC prefixed Operation Outcome codes and provide clear and concise diagnostics texts
• There should be no need to omit or use a different prefix when responding to requests
• There will be times where it is not possible to generate a response in the above format
• In the event this occurs, a relevant HTTP response code should be the minimum
• Log errors locally for incident investigation by IT support staff
• If the request is problematic, this should be logged specifically as a sender system issue
• Details of the sender system should be logged to support investigation
• As a minimum, the Operation Outcome must include:
  • The HTTP Response code
  • The Operation Outcome code
  • Clear and concise diagnostics information

Failure Scenarios

For More Detail on error handling, there is specific information on failure scenarios available in the Failure Scenarios section.