Error Handling - Overview

Introduction

There are several points at which an error may occur to prevent the booking operations completing successfully.

The following guidance is for “Care Connect” booking. GP Connect is very similar but has specific guidance here.

Overview

Error codes are returned by the APIs used to connect to each service. Error codes are meant for developer use only - they should not be presented to end-users. Instead, Consumer applications should interpret the codes and provide user-friendly resolution steps on failure. Consumer and Provider systems should record the detailed error codes in local logs in order to support service incident investigation.

As the process is initiated by a Consumer there could be several stages that create issues - this table provides a high-level overview of each stage and then follows with specific sections to detail the error handling process and Consumer and Provider responsibilities.

Consumer → DOS

The DOS will return specific errors when searching for services. These are detailed here.

These errors are all about:

• Technical issues with connecting to DOS, which should be investigated by local IT Support; or
• No valid services being returned, which should be handled locally with agreed processes for widening search parameters. Note that successful completion of a DOS Search may occur, but provide incomplete or erroneous data for the booking process to continue due to poor data quality.

Common issues with data held in the DOS that will be discovered later:

• Service information returned that supports booking, but a FHIR scheduling endpoint is not entered against the service or is not formatted correctly. This will result in failure later when using SDS to retrieve the endpoint information. This is an issue with DOS configuration and should be investigated with the DOS Leads.
• Service information returned but no FHIR endpoint is configured even though booking is permitted.

Consumer responsibilities:

1. Log errors returned by DOS for incident investigation
2. Inform end-user with a suitable message appropriate to the business flow e.g. critical error with advice to call local IT helpdesk, or business process options to warn users to choose another service
3. Ensure information for appropriate local incident management is captured

Consumer → SDS

The SDS will return specific errors when searching for an endpoint, for more information see the Spine Directory Service - LDAP API and the Spine External Interface Specification (EIS). In the event that a SDS query does not return an FHIR endpoint, this should be raised with NHS Digital using the existing support process.

Consumer responsibilities:

1. Log errors returned by SDS for local and potential NHS Digital incident investigation
2. Inform end-user with a suitable message appropriate to the business flow e.g. critical error with advice to call local IT helpdesk, or business process options to warn users to choose another service
3. Ensure information for appropriate local incident management is captured

Consumer → SSP

If the SSP determines the endpoint is valid using the supplied ASID, then it will forward the request to the FHIR endpoint of the Provider system. The SSP will act as a true proxy here and passthrough requests and responses between Consumer and Provider systems.

However, there are instances where the request will fail before the Provider system receives the requests.

SSP will return specific HTTP error codes under these circumstances as per the following approach:

https://developer.nhs.uk/apis/spine-core/api_spine-operationoutcome.html

https://developer.nhs.uk/apis/spine-core/ssp_implementation_guide.html

Here are examples of errors returned by SSP as error codes:

Consumer responsibilities:

1. Log errors returned by SSP for incident investigation by IT support staff
2. Inform end-user with a suitable message appropriate to the business flow e.g. critical error with advice to call local IT helpdesk, or business process options to warn users to choose another service
3. Ensure information for appropriate local incident management is captured

Consumer → SSP → Provider

Providers MUST respond to errors processing requests from a Consumer system as per the guidance below. The SSP will forward the responses unchanged.

For Care Connect booking workflows, the process is very similar to GP Connect. However, the Care Connect APIs have standardised on the approach to error handling to use the standard HL7 FHIR OperationOutcome resource.

The error code guidance is provided for each capability in the FHIR NHS Scheduling API Specification

Provider System responsibilities

1. Log errors locally for incident investigation by IT support staff. If the Request is malformed, this should be logged specifically as a Consumer system issue. Details of the Consumer system should be logged to support investigation e.g. Org ID.
2. On error send an appropriate HTTP 4xx or 5xx error code and an OperationOutcome resource. Use the sections of the OperationOutcome resource to send detailed information back to the Consumer system on what went wrong and why. This is especially important if there was an error in the Request, as this will help the Consumer support function diagnose what is wrong with their system or configuration.
3. As a minimum the OperationOutcome resource must contain:
   • A provider id for the outcome e.g. a local id to identify local error codes or a text description
   • An issue severity code
   • An issue code

Example

{
  "resourceType": "OperationOutcome",
  "id": "ERR-23451",
  "meta": {
    "profile": [
      "https://www.hl7.org/fhir/STU3/operationoutcome.html"
    ]
  },
  "issue": [
    {
      "severity": "error",
      "code": "value",
      "details": {
        "coding": [
          {
            "system": "https://fhir.nhs.uk/STU3/ValueSet/Spine-ErrorOrWarningCode-1",
            "code": "INVALID_NHS_NUMBER"
          }
        ]
      },
      "diagnostics": "Any further internal debug details i.e. stack trace details etc."
    }
  ]
}

The next table details the appropriate error code return values to be sent by Provider systems for important common issues that may occur for each interaction. In addition, the table details specific information that should be appended into the OperationOutcome response by Provider systems. Providers MUST implement these as a minimum.

Consumer System responsibilities

1. Log errors returned by Provider systems for incident investigation by IT support staff. If the Response is malformed, this should be logged specifically as a Provider system issue. Details of the Provider system should be logged to support investigation e.g. DOS Service ID.
2. Inform end-user with a suitable message appropriate to the business flow e.g. critical error with advice to call local IT helpdesk, or business process options (e.g. to warn users to choose another service)
3. Ensure information for appropriate local incident management is captured.