NHS Booking and Referral Standard

Guide v1.0.1 | Core v1.0.0

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.

Interaction Error Handling Overview Operation Outcome Prefix
Sender querying a Service Discovery tool As an existing solution, the DOS APIs return a number of significant errors specific to the actual API failing. These are all self-contained in that process. These are documented in a link below and will not affect the ongoing activity unless the data returned in the query is erroneous and then cause the next stages of the process to either fail or not be possible. N/A
Sender interactions with the BaRS API Interactions with the BaRS API may fail due to, but not limited to, the following reasons: The service being unavailable to the sender, the Sender being unauthenticated, the Sender reaching or exceeding a rate limit, or badly formed requests being sent. SEND
BaRS Service internal interactions Depending on the operation requested, internal interactions may fail within the proxy due to non-existent resources, service failures or data related issues within the Senders payload. PROXY
BaRS interaction with the Receiver In the event BaRS successfully proxies a request through to a Receiver, the Receiver may still respond with an error due to authentication, authorization or data related issues within the Senders payload, assuming the endpoint is available. REC

HTTP response codes and operation outcomesBaRS 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.

HTTP Code Code Value Description Example diagnostics text
400 SEND_BAD_REQUEST The API was unable to process the request. "The API was unable to process the request: <further diagnostics information, error message/error text>"
REC_BAD_REQUEST The Receiver has responded stating the message was malformed. "<Receiver Identifier (ODS)> was unable to process the request: <further diagnostics information, error message/error text>"
PROXY_BAD_REQUEST Though Unlikely, BaRS, having accepted the message; has received a 400 response from an internal component. "BaRS was unable to process the request: <further diagnostics information, error message/error text>"
404 PROXY_NOT_FOUND The resource was not found within BaRS. "The resource was not found within BaRS: <further diagnostics information, error message/error text>"
REC_NOT_FOUND The resource was not found at the Receiver. "<Receiver Identifier (ODS)> encountered a conflict: <further diagnostics information, error message/error text>"
409 REC_CONFLICT Example: Sender is trying to Book an appointment in a slot that doesn't allow booking. "<Receiver Identifier (ODS)> encountered a conflict: <further diagnostics information, error message/error text>"
501 SEND_NOT_IMPLEMENTED The Request was not recognized. "The Request was not recognized by the API: <further diagnostics information, error message/error text>"
REC_NOT_IMPLEMENTED The Receiver did not recognize the request. "The Request was not recognised by the Receiver - <Receiver identifier (ODS)>: <further diagnostics information, error message/error text>"
PROXY_NOT_IMPLEMENTED BaRS did not recognize the request. "This Request was not recognized by the proxy: <further diagnostics information, error message/error text>"

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
{

  "resourceType": "OperationOutcome",

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

  "meta": {

  "profile": [

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

    ]

  },

  "issue": [

    {

      "severity": "error",

      "code": "not-found",

      "details": {

        "coding": [

          {

            "system": "http://hl7.org/fhir/ValueSet/operation-outcome",

            "code": "REC_NOT_FOUND",

            "display": "404 - REC_NOT_FOUND"

          }

        ]

      },

      "diagnostics": "The resource was not found at the <Receiver Identifier (ODS)>: <further diagnostics information, error message/error text>"

    }

  ]

}

Failure Scenarios

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

back to top