Implementation guide for interoperable medicines

This guidance is under active development by NHS England and content may be added or updated on a regular basis.

Profile: OperationOutcome

Command 'tree' could not render: Project was not found for nhsdigitalspine/nhsdigital-operationoutcome.
Command 'dict' could not render: Project was not found for nhsdigitalspine/nhsdigital-operationoutcome.

In the event of a RESTful interaction or operation failure, an OperationOutcome resource is used to convey specific detailed processable error information back to the client as part of the HTTP response.

National FHIR APIs delivered by NHS Digital will use a profiled version of this resource; NHSDigital-OperationOutcome. Local implementations should consider using this resource as it contains a comprehsnive value-set of error codes and would give consistancy between local and national API error handling.

In addition to the mandatory elements, the OperationOutcome should contain details of the error code in the OperationOutcome.issue.details.coding.code and OperationOutcome.issue.details.coding.display fields.

The OperationOutcome should provide additional diagnostic details of the error in the OperationOutcome.diagnostics property where such details securely provide additional error context for consumer applications. Patient identifiable data should not be included within this property.

Note: The sections below provide guidance on the error details to be returned in a number of key scenarios.

Malformed request errors

When the server cannot or will not process a request due to an apparent client error then the following BAD_REQUEST error MUST be used to return debug details.

HTTP code Issue type Error code Error message
400 invalid BAD_REQUEST Submitted request is malformed / invalid.

BAD_REQUEST Spine error codes be used in the following types of scenario:

  • JWT claims information is not valid JSON, is null, or has an invalid value
  • invalid FHIR resource in JWT claim (for example, a Patient resource when Practitioner expected)
  • malformed JSON or XML content in request body
  • an expected header is missing or invalid
  • invalid HTTP verb used

Example: Malformed JSON Web Token in request

For example, if the request contained a null claim within a JSON Web Token (JWT), then the following error details would be returned:

{
    "resourceType": "OperationOutcome",
    "meta": {
        "profile": [
            "https://fhir.nhs.uk/StructureDefinition/NHSDigital-OperationOutcome"
        ]
    },
     "issue": [
        {
            "severity": "error",
            "code": "invalid",
            "details": {
                "coding": [
                    {
                        "system": "https://simplifier.net/guide/NHSDigital/NHSDigital-OperationOutcome-Codes",
                        "code": "BAD_REQUEST",
                        "display": "Bad request"
                    }
                ]
            },
            "diagnostics": "Malformed JWT"
        }
    ]
}

Resource validation errors

Where FHIR resource validation issues arise during processing of consumer requests, provider systems MUST utilise one the following error details:

HTTP code Issue type Error code Error message
422 invalid INVALID_RESOURCE Submitted resource is not valid.
422 invalid INVALID_PARAMETER Submitted parameter is not valid.
422 invalid REFERENCE_NOT_FOUND Referenced resource not found.

Detailed diagnostic information MUST be supplied when erroring on the codes above.

INVALID_PARAMATER would be used in the following, or similar, scenarios:

  • An invalid date / time value specified in a custom operation parameter.

INVALID_RESOURCE would be used in situations such as the following:

  • The resource failed structural validation
  • A resource failed to be procesed because of a FHIR constraint, or other rule application, where the error is not already covered by other error codes

REFERENCE_NOT_FOUND describes a scenario where a consumer POSTs a FHIR resource which contains a FHIR reference that cannot be found.

Example: Reference not found

For example, if a MedicationRequest referenced a Practitioner resource that could not be found or resolved by the server. The following error details would be returned:

{
    "resourceType": "OperationOutcome",
    "meta": {
        "profile": [
            "https://fhir.nhs.uk/StructureDefinition/NHSDigital-OperationOutcome"
        ]
    },
    "issue": [
        {
            "severity": "error",
            "code": "invalid",
            "details": {
                "coding": [
                    {
                        "system": "https://simplifier.net/guide/NHSDigital/NHSDigital-OperationOutcome-Codes",
                        "code": "REFERENCE_NOT_FOUND",
                        "display": "FHIR reference not found"
                    }
                ]
            },
            "diagnostics": "Referenced Practitioner resource not found"
        }
    ]
}

Duplicate errors

When responding to consumer API requests, provider systems MUST return one of the following OperationOutcome details when a resource could not be created or updated because it would cause a duplicate in the provider system:

HTTP code Issue type Error code Error message
409 duplicate DUPLICATE_REJECTED Create would lead to creation of a duplicate resource

For example, if the ePMA system attempted to send a MedicationRequest that is already an active record on the pharmacy system the error details would be returned:

{
    "resourceType": "OperationOutcome",
    "meta": {
        "profile": [
            "https://fhir.nhs.uk/StructureDefinition/NHSDigital-OperationOutcome"
        ]
    },
    "issue": [
        {
            "severity": "error",
            "code": "duplicate",
            "details": {
                "coding": [
                {
                    "system": "https://simplifier.net/guide/NHSDigital/NHSDigital-OperationOutcome-Codes",
                    "code": "DUPLICATE_REJECTED",
                    "display": "Create would lead to creation of duplicate resource"
                }
            ]
        },
        "diagnostics": "MedicationRequest record already exists with that logical identifier"
    }
  ]
}

Security validation errors

When a client system does not present correct security parameters, provider systems MUST return one of the following OperationOutcome details:

HTTP code Issue type Error code Error message
403 forbidden ACCESS_DENIED Access denied

Example: Access denied

In this scenario as resource has attempted to be accessed which the requesting user is not authoriused to view.

The JSON below represents an example response that could be returned.

{
    "resourceType": "OperationOutcome",
    "meta": {
        "profile": [
            "https://fhir.nhs.uk/StructureDefinition/NHSDigital-OperationOutcome"
        ]
    },
    "issue": [
    {
        "severity": "error",
        "code": "forbidden",
        "details": {
            "coding": [
                {
                    "system": "https://simplifier.net/guide/NHSDigital/NHSDigital-OperationOutcome-Codes",
                    "code": "ACCESS_DENIED",
                    "display": "Access denied"
                }
            ]
        },
        "diagnostics": "Invalid authorisation token."
    }
  ]
}

Identity validation errors

Provider systems MUST respond by returning one of the following OperationOutcome error codes where FHIR resource identity error scenarios are encountered:

HTTP code Issue type Error code Error message
400 value INVALID_IDENTIFIER_SYSTEM Invalid identifier system
400 value INVALID_IDENTIFIER_VALUE Invalid identifier value
400 value INVALID_NHS_NUMBER NHS number invalid
404 not-found ORGANISATION_NOT_FOUND Organisation record not found
404 not-found PATIENT_NOT_FOUND Patient record not found
404 not-found PRACTITIONER_NOT_FOUND Practitioner record not found
404 not-found NO_RECORD_FOUND No record found

Example: An invalid NHS Number was supplied

In this scenario an invalid NHS number value was supplied.

The JSON below represents an example response that could be returned.

{
    "resourceType": "OperationOutcome",
    "meta": {
        "profile": [
            "https://fhir.nhs.uk/StructureDefinition/NHSDigital-OperationOutcome"
        ]
    },
    "issue": [
        {
            "severity": "error",
            "code": "value",
            "details": {
                "coding": [
                    {
                        "system": "https://simplifier.net/guide/NHSDigital/NHSDigital-OperationOutcome-Codes",
                        "code": "INVALID_NHS_NUMBER",
                        "display": "Invalid NHS number"
                    }
                ]
            }
        }
    ]
}

Example: The patient could not be found

In this scenario a valid NHS number value was supplied; however, a local record did not exist for the patient in question.

The JSON below represents an example response that could be returned.

{
    "resourceType": "OperationOutcome",
    "meta": {
        "profile": [
            "https://fhir.nhs.uk/StructureDefinition/NHSDigital-OperationOutcome"
        ]
    },
    "issue": [
        {
            "severity": "error",
            "code": "not-found",
            "details": {
                "coding": [
                    {
                        "system": "https://fhir.nhs.uk/STU3/ValueSet/Spine-ErrorOrWarningCode-1",
                        "code": "PATIENT_NOT_FOUND",
                        "display": "Patient not found"
                    }
            ]
        }
    }
  ]
}

Internal server errors

When the FHIR server has received a request for an operation or FHIR resource which is not (yet) implemented, then the NOT_IMPLEMENTED Spine error code MUST be used.

HTTP code Issue type Error code Error message
501 not-supported NOT_IMPLEMENTED FHIR resource or operation not implemented at server.

When the error is unexpected and the server can’t be more specific on the exact nature of the problem then the INTERNAL_SERVER_ERROR Spine error code MUST be used, and diagnostics MUST be included to provide detail of the error.

HTTP code Issue type Error code Error message
500 processing INTERNAL_SERVER_ERROR Unexpected internal server error.

Example: Unexpected exception

For example, if an unexpected internal exception is thrown by either an Operation or RESTful API, then the following error details would be returned:

{
    "resourceType": "OperationOutcome",
    "meta": {
        "profile": [
            "https://fhir.nhs.uk/StructureDefinition/NHSDigital-OperationOutcome"
        ]
    },
    "issue": [
        {
            "severity": "error",
            "code": "exception",
            "details": {
                "coding": [
                    {
                        "system": "https://simplifier.net/guide/NHSDigital/NHSDigital-OperationOutcome-Codes",
                        "code": "INTERNAL_SERVER_ERROR",
                        "display": "Internal server error"
                    }
                ]
            },
            "diagnostics": "Any further internal debug details i.e. stack trace details etc."
        }
  ]
}
back to top