NHS England FHIR Implementation Guide (deprecated)

Important Announcement regarding this Implementation Guide
  • As of 04/10/2023, this implementation guide has been deprecated and all development on the legacy NHS England FHIR Implementation Guide assets has ceased.
  • Therefore, vendors looking to start new implementations or looking to update existing implementations should use the new NHS England Implementation Guide. Vendors continuing to implement legacy NHS England FHIR Implementation Guide based solutions do so at their own risk and on the understanding that no maintenance or support will be available.

NHSDigital-OperationOutcome

Conformance url FHIR Module Maturity Level
https://fhir.nhs.uk/StructureDefinition/NHSDigital-OperationOutcome Implementation Support normative

Conformance Rules



with OperationOutcome

idΣ0..1System.String
versionIdΣ0..1id
lastUpdatedΣ1..1instant
sourceΣ0..1uri
profileΣ0..*canonical(StructureDefinition)
securityΣ0..*CodingBinding
tagΣ0..*Coding
supportingInfoI0..*Extension(Reference(Resource))
severityS Σ1..1codeBinding
codeS Σ1..1codeBinding
systemΣ1..1uri
versionΣ0..1string
codeΣ1..1code
displayΣ0..1string
userSelectedΣ0..1boolean
textΣ0..1string
diagnosticsS Σ0..1string
locationS Σ0..*string
expressionS Σ0..*string

from OperationOutcome

idΣ0..1System.String
versionIdΣ0..1id
lastUpdatedΣ1..1instant
sourceΣ0..1uri
profileΣ0..*canonical(StructureDefinition)
securityΣ0..*CodingBinding
tagΣ0..*Coding
supportingInfoI0..*Extension(Reference(Resource))
severityS Σ1..1codeBinding
codeS Σ1..1codeBinding
systemΣ1..1uri
versionΣ0..1string
codeΣ1..1code
displayΣ0..1string
userSelectedΣ0..1boolean
textΣ0..1string
diagnosticsS Σ0..1string
locationS Σ0..*string
expressionS Σ0..*string

keyhumanseverityexpression
nhsd-errrorcodeAn NHS Digital error or warning code is requirederror(severity = 'information') or ((severity != 'information') and details.empty().not())

API Error or Warning Codes

codedisplaydefinition
ACCESS_DENIEDAccess has been denied to process this requestAlthough authenticated - the system or user does not have permission for a particular request. Recommend using HTTP Status Code 403
ACCESS_DENIED_LEVELAccess has been denied because you need higher level permissionsThe request requires higher pemission levels than the authentication provided. For example NHS login has three main levels of P0, P5 and P9 - and the request held a P0 level, instead of P9. Recommend using HTTP Status Code 403
ACCESS_TOKEN_EXPIREDAccess token has expiredObtain a new access token - the provided access token has expired and is no longer valid, access tokens only have a short life time. Recommend using HTTP Status Code 401
ACCESS_TOKEN_INVALIDAuthorization header not formatted correctlyThe bearer token could not be retrieved from the Authorization header, format should be 'Bearer INSERT-ACCESS-TOKEN'. Recommend using HTTP Status Code 401
ACCESS_TOKEN_MISSINGAuthorization header not sentThe access token must be passed in the Authorization header. The format should be 'Bearer INSERT-ACCESS-TOKEN'. Recommend using HTTP Status Code 400
TIMEOUTRequest has timed outThe request has not responded in the timeout period, retry the request. Recommend using HTTP Status Code 408
TOO_MANY_REQUESTSYour connection has exceeded the rate limitAPIs have different rate limits - and your request has been rejected. Rate limits can be per application (connection) or per API. A detailed reason will be returned in the diagnoistics field. Wait a short period and re-try, ideally with an exponential back-off policy. Recommend using HTTP Status Code 429
METHOD_NOT_ALLOWEDMethod not allowedThe request method (verb) is not permitted on this endpoint. Recommend using HTTP Status Code 405
SERVICE_UNAVAILABLEService unavailable - could be temporaryThere has been a processing failure in the request chain. This could be tranisent failure for a single request, a temporary service issue or maintenance window. Re-send the request after the time specified in the Retry-After header. Normally maps to HTTP Status Code 503
SERVICE_ERRORService failure or unexpected errorThere has been server or service problem and it could be limited to this one request. Re-send the request after a short period of time. Normally maps to HTTP Status Code 500
RESOURCE_NOT_FOUNDResource not foundThe URL did not point to an existing resource. This could be a simple incorrect url path, or for some REST APIs this can equate to a person or prescription not existing in that API. Recommend using HTTP Status Code 404
MISSING_HEADERA required header is missingInform the caller which required header is missing in the request. Some APIs will return a list of missing headers, others will return the first one. If a list is returned, there will be one issue per error. Recommend using HTTP Status Code 400
VALIDATION_ERRORA paremeter or value has resulted in a validation errorReturns which parameter or value was incorrect, and why. Some APIs will return a list of errors, others will return the first one. If a list is returned, there will be one issue per error. Recommend using HTTP Status Code 400
MISSING_VALUEA required value is missingInform the caller which value is missing value in the request. Recommend using HTTP Status Code 400
NOT_ACCEPTABLECompatible content was not availableThe request content string did not result in a matching content type that could be returned. If an API version was requested and it is invalid the message should make that clear. Recommend using HTTP Status Code 406

Example HL7 FHIR Validation Error

{
    "resourceType": "OperationOutcome",
    "id": "1a388581-dbbe-43e3-9054-f5976c0245e5",
    "meta": {
        "lastUpdated": "2021-04-21T16:58:00+00:00"
    },
    "issue":  [
        {
            "severity": "information",
            "code": "processing",
            "diagnostics": "This element does not match any known slice defined in the profile https://fhir.nhs.uk/StructureDefinition/NHSDigital-Patient",
            "location":  [
                "Patient.identifier[1]",
                "Line 1, Col 651"
            ]
        },
        {
            "severity": "error",
            "code": "processing",
            "details": {
                "coding":  [
                    {
                        "system": "https://fhir.nhs.uk/CodeSystem/Spine-ErrorOrWarningCode",
                        "code": "INVALID_VALUE",
                        "display": "Invalid value"
                    }
                ]
            },
            "diagnostics": "Patient.gender: minimum required = 1, but only found 0 (from https://fhir.nhs.uk/StructureDefinition/NHSDigital-Patient)",
            "location":  [
                "Patient",
                "Line 1, Col 37"
            ]
        }
    ]
}

Example Data Business Rule Error

{
    "resourceType": "OperationOutcome",
    "id": "rrt-2959959087381887325-c-geu2-24001-82918062-1",
    "meta": {
        "lastUpdated": "2021-04-14T11:35:00+00:00"
    },
    "issue":  [
        {
            "severity": "error",
            "code": "value",
            "details": {
                "coding":  [
                    {
                        "system": "https://fhir.nhs.uk/CodeSystem/Spine-ErrorOrWarningCode",
                        "code": "INVALID_VALUE",
                        "display": "Invalid value"
                    }
                ]
            },
            "diagnostics": "(invalid_request) firstName is missing",
            "location":  [
                "/data/attributes/firstName"
            ]
        }
    ]
}
back to top