NHSDigital · nhsd-david-wass · Apr 25, 2025 · Mar 26, 2025 · Mar 26, 2025 · Mar 27, 2025
@@ -12,7 +12,7 @@
   "license": "MIT",
   "homepage": "https://github.com/NHSDigital/e-referrals-service-api",
   "dependencies": {
-    "@redocly/cli": "^1.34.0"
+    "@redocly/cli": "^1.34.2"
   },
   "devDependencies": {
     "apigeetool": "^0.16.5",

@@ -1,6 +1,6 @@
-<AssignMessage async="false" continueOnError="false" enabled="true" name="AssignMessage.AuthenticationOperationOutcomeErrorResponse">
+<AssignMessage async="false" continueOnError="false" enabled="true" name="AssignMessage.OperationOutcomeErrorResponse">
     <Set>
-        <StatusCode>401</StatusCode>
+        <StatusCode>{status_code}</StatusCode>
         <ReasonPhrase>Unauthorized</ReasonPhrase>
         <Payload contentType="application/fhir+json" variablePrefix="%" variableSuffix="#">{ "resourceType": "OperationOutcome", "meta": { "lastUpdated": "%current_timestamp#", "profile" : [ "%op_outcome_fhir_profile#" ] }, "issue": [ { "severity": "error", "code": "%op_outcome_issue_code#", "details": { "coding": [ { "system": "%op_outcome_issue_details_coding_system#", "code": "%op_outcome_issue_details_coding_code#" } ] }, "diagnostics": "%faultstring#" } ] }</Payload>
     </Set>

@@ -1,4 +1,8 @@
 <AssignMessage enabled="true" name="AssignMessage.SetOperationOutcomeIssueCodeLogin">
+    <AssignVariable>
+        <Name>status_code</Name>
+        <Value>401</Value>
+    </AssignVariable>
     <AssignVariable>
         <Name>op_outcome_issue_code</Name>
         <Value>login</Value>

@@ -1,4 +1,8 @@
 <AssignMessage enabled="true" name="AssignMessage.SetOperationOutcomeIssueIal">
+    <AssignVariable>
+        <Name>status_code</Name>
+        <Value>401</Value>
+    </AssignVariable>
     <AssignVariable>
         <Name>op_outcome_issue_code</Name>
         <Value>forbidden</Value>

@@ -0,0 +1,14 @@
+<AssignMessage enabled="true" name="AssignMessage.SetOperationOutcomeMissingAsid">
+    <AssignVariable>
+        <Name>op_outcome_issue_code</Name>
+        <Value>forbidden</Value>
+    </AssignVariable>
+    <AssignVariable>
+        <Name>faultstring</Name>
+        <Value>ASID is not configured in the application</Value>
+    </AssignVariable>
+    <AssignVariable>
+        <Name>status_code</Name>
+        <Value>403</Value>
+    </AssignVariable>
+</AssignMessage>
@@ -0,0 +1,10 @@
+<RaiseFault async="false" continueOnError="false" enabled="true" name="RaiseFault.MissingAsid">
+    <FaultResponse>
+        <Set>
+            <Payload contentType="text/plain"/>
+            <StatusCode>403</StatusCode>
+            <ReasonPhrase>Forbidden</ReasonPhrase>
+        </Set>
+    </FaultResponse>
+    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
+</RaiseFault>
@@ -15,7 +15,7 @@
                 <Name>AssignMessage.SetOperationOutcomeIssueCodeLogin</Name>
             </Step>
             <Step>
-                <Name>AssignMessage.AuthenticationOperationOutcomeErrorResponse</Name>
+                <Name>AssignMessage.OperationOutcomeErrorResponse</Name>
             </Step>
             <Condition>(oauthV2.OauthV2.VerifyAccessToken.failed = true) and (isFhirR4Path = true)</Condition>
         </FaultRule>
@@ -43,7 +43,7 @@
                 <Condition>aalError != true</Condition>
             </Step>
             <Step>
-                <Name>AssignMessage.AuthenticationOperationOutcomeErrorResponse</Name>
+                <Name>AssignMessage.OperationOutcomeErrorResponse</Name>
                 <Condition>aalError = true</Condition>
             </Step>
             <Condition>(oauthV2.OauthV2.VerifyAccessToken.failed = true) and (isFhirR4Path = false)</Condition>
@@ -85,10 +85,27 @@
                 <Name>AssignMessage.SetOperationOutcomeIssueIal</Name>
             </Step>
             <Step>
-                <Name>AssignMessage.AuthenticationOperationOutcomeErrorResponse</Name>
+                <Name>AssignMessage.OperationOutcomeErrorResponse</Name>
             </Step>
             <Condition>(raisefault.RaiseFault.401InsufficientIal.failed = true)</Condition>
         </FaultRule>
+        <FaultRule name="missing_asid">
+            <Step>
+                <Condition>(isFhirR4Path = true)</Condition>
+                <Name>AssignMessage.SetOperationOutcomeVariablesR4</Name>
+            </Step>
+            <Step>
+                <Condition>(isFhirR4Path = false)</Condition>
+                <Name>AssignMessage.SetOperationOutcomeVariablesPreR4</Name>
+            </Step>
+            <Step>
+                <Name>AssignMessage.SetOperationOutcomeMissingAsid</Name>
+            </Step>
+            <Step>
+                <Name>AssignMessage.OperationOutcomeErrorResponse</Name>
+            </Step>
+            <Condition>(raisefault.RaiseFault.MissingAsid.failed = true)</Condition>
+        </FaultRule>
     </FaultRules>
     <PreFlow>
         <Request>
@@ -101,6 +118,10 @@
             <Step>
                 <Name>OauthV2.VerifyAccessToken</Name>
             </Step>
+            <Step>
+                <Name>RaiseFault.MissingAsid</Name>
+                <Condition>(app.asid == null) Or (app.asid == "")</Condition>
+            </Step>
             <Step>
                 <Name>AssignMessage.PopulateAsidFromApp</Name>
             </Step>

@@ -28,9 +28,9 @@ semver = "^3.0.4"
 gitpython = "^3.1.44"
 lxml = "^4.9.4"
 xmlformatter = "^0.2.8"
-pytest-check = "^2.5.1"
+pytest-check = "^2.5.3"
 requests = "^2.32.3"
-openapi-core = "^0.19.4"
+openapi-core = "^0.19.5"
 
 
 [tool.poetry.group.dev.dependencies]
@@ -39,7 +39,7 @@ black = "^25.1"
 pip-licenses = "^5.0.0"
 jinja2 = "^3.1.6"
 pytest = "^8.3.5"
-pytest-asyncio = "^0.25.3"
+pytest-asyncio = "^0.26.0"
 pytest-nhsd-apim = "^3.4.5"
 
 [tool.poetry.scripts]

@@ -0,0 +1,21 @@
+{
+    "resourceType": "OperationOutcome",
+    "meta": {
+      "lastUpdated": "2022-03-01T10:00:00.42Z"
+    },
+    "issue": [
+      {
+        "severity": "error",
+        "code": "transient",
+        "details": {
+          "coding": [
+            {
+              "system": "https://fhir.nhs.uk/CodeSystem/http-error-codes",
+              "code": "REC_UNAVAILABLE"
+            }
+          ]
+        }
+      }
+    ]
+  }
+
@@ -0,0 +1,23 @@
+{
+    "meta": {
+      "profile": [
+        "https://fhir.nhs.uk/STU3/StructureDefinition/eRS-OperationOutcome-1"
+      ]
+    },
+    "resourceType": "OperationOutcome",
+    "issue": [
+      {
+        "severity": "error",
+        "code": "transient",
+        "details": {
+          "coding": [
+            {
+              "system": "https://fhir.nhs.uk/STU3/CodeSystem/eRS-APIErrorCode-1",
+              "code": "SYSTEM_UNAVAILABLE",
+              "display": "System Unavailable"
+            }
+          ]
+        }
+      }
+    ]
+  }
@@ -0,0 +1,23 @@
+{
+  "meta": {
+    "profile": [
+      "https://fhir.nhs.uk/STU3/StructureDefinition/eRS-OperationOutcome-1"
+    ]
+  },
+  "resourceType": "OperationOutcome",
+  "issue": [
+    {
+      "severity": "error",
+      "code": "login",
+      "details": {
+        "coding": [
+          {
+            "system": "https://fhir.nhs.uk/STU3/CodeSystem/eRS-APIErrorCode-1",
+            "code": "NO_ACCESS"
+          }
+        ]
+      },
+      "diagnostics": "Example diagnostics message."
+    }
+  ]
+}
@@ -111,3 +111,5 @@ responses:
     $ref: '../responses/TooManyRequests.yaml'
   '500':
     $ref: '../responses/InternalServerError.yaml'
+  '503':
+    $ref: '../responses/ServiceUnavailable.yaml'
@@ -67,3 +67,5 @@ responses:
     $ref: '../responses/TooManyRequests.yaml'
   '500':
     $ref: '../responses/InternalServerError.yaml'
+  '503':
+    $ref: '../responses/ServiceUnavailable.yaml'
@@ -77,3 +77,5 @@ responses:
     $ref: '../responses/TooManyRequests.yaml'
   '500':
     $ref: '../responses/InternalServerError.yaml'
+  '503':
+    $ref: '../responses/ServiceUnavailable.yaml'
@@ -64,3 +64,5 @@ responses:
     $ref: '../responses/TooManyRequests.yaml'
   '500':
     $ref: '../responses/InternalServerError.yaml'
+  '503':
+    $ref: '../responses/ServiceUnavailable.yaml'
@@ -55,3 +55,5 @@
           $ref: '../responses/TooManyRequests.yaml'
         '500':
           $ref: '../responses/InternalServerError.yaml'
+        '503':
+          $ref: '../responses/ServiceUnavailable.yaml'
@@ -79,3 +79,5 @@ responses:
     $ref: '../responses/TooManyRequests.yaml'
   '500':
     $ref: '../responses/InternalServerError.yaml'
+  '503':
+    $ref: '../responses/ServiceUnavailable.yaml'
@@ -94,4 +94,6 @@ responses:
   '429':
     $ref: '../responses/TooManyRequests.yaml'
   '500':
-    $ref: '../responses/InternalServerError.yaml'
+    $ref: '../responses/InternalServerError.yaml'
+  '503':
+    $ref: '../responses/ServiceUnavailable.yaml'
@@ -0,0 +1,6 @@
+description: |
+  Defines a period (in seconds) after which the client should attempt their request again.
+required: false
+schema:
+  type: string
+  example: '120'
@@ -5,6 +5,7 @@ description: |
   | issue.details.coding.code | issue.code | Coding System                                                      | Description                                                                        |
   | ------------------------- | ---------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------- |
   | REC_FORBIDDEN             | forbidden  | [BaRS Error Code](https://fhir.nhs.uk/CodeSystem/http-error-codes) | A call attempts to access or operate upon a resource without proper authorisation. |
+  | ACCESS_DENIED             | forbidden  | [APIM Error Code](https://fhir.nhs.uk/CodeSystem/NHSD-API-ErrorOrWarningCode) | The request could not be authenticated due to insufficient credentials being provided. |
 
 headers:
   X-Correlation-ID:
@@ -18,4 +19,4 @@ content:
     schema:
       $ref: '../NHSDigital-OperationOutcome.yaml'
     example:
-      $ref: '../../examples/NHSDigital-OperationOutcome-403.json'
+      $ref: '../../examples/NHSDigital-OperationOutcome-403.json'
@@ -0,0 +1,23 @@
+description: |
+  Where status code 503 (Service Unavailable) is returned then an [NHSDigital-OperationOutcome](https://fhir.nhs.uk/StructureDefinition/NHSDigital-OperationOutcome) will be included in the body, as detailed below.
+  In response to receiving this status code, it is recommended that clients retry at a later time based on a returned `Retry-After` header when provided.
+
+  | issue.details.coding.code | issue.code | Coding System                                                      | Description                                                                                                                          |
+  | ------------------------- | ---------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
+  | REC_UNAVAILABLE           | transient  | [BaRS Error Code](https://fhir.nhs.uk/CodeSystem/http-error-codes) | A request to an internal component timed out whilst attempting to serve a response or the system is currently otherwise unavailable. |
+
+headers:
+  X-Correlation-ID:
+    $ref: '../headers/response/CorrelationID.yaml'
+  X-Request-ID:
+    $ref: '../headers/response/RequestID.yaml'
+  Content-Type:
+    $ref: '../headers/response/ContentTypeFhirJson.yaml'
+  Retry-After:
+    $ref: '../headers/response/RetryAfter.yaml'
+content:
+  application/fhir+json:
+    schema:
+      $ref: '../NHSDigital-OperationOutcome.yaml'
+    example:
+      $ref: '../../examples/NHSDigital-OperationOutcome-503.json' 
@@ -4,7 +4,7 @@ description: |
 
   | issue.details.coding.code | issue.code       | Coding System                                                                 | Description                                                                                                                                                                              |
   | ------------------------- | ---------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-  | ACCESS_DENIED             | login            | [APIM Error Code](https://fhir.nhs.uk/CodeSystem/NHSD-API-ErrorOrWarningCode) | The request could not be authenticated due to either no credentials being provided or the provided credentials no longer being valid. Callers receiving this code should reauthenticate. |
+  | ACCESS_DENIED             | <ul><li>login</li><li>forbidden</li></ul> | [APIM Error Code](https://fhir.nhs.uk/CodeSystem/NHSD-API-ErrorOrWarningCode) | The request could not be authenticated due to either no credentials being provided or the provided credentials no longer being valid. Callers receiving this code should reauthenticate. |
 headers:
   X-Correlation-ID:
     $ref: '../headers/response/CorrelationID.yaml'
@@ -15,4 +15,4 @@ content:
     schema:
       $ref: '../NHSDigital-OperationOutcome.yaml'
     example:
-      $ref: '../../examples/NHSDigital-OperationOutcome-401.json'
+      $ref: '../../examples/NHSDigital-OperationOutcome-401.json'
@@ -93,3 +93,5 @@ responses:
     $ref: '../responses/TooManyRequests.yaml'
   '500':
     $ref: '../responses/InternalServerError.yaml'
+  '503':
+    $ref: '../responses/ServiceUnavailable.yaml'
@@ -90,3 +90,5 @@ responses:
     $ref: '../responses/TooManyRequests.yaml'
   '500':
     $ref: '../responses/InternalServerError.yaml'
+  '503':
+    $ref: '../responses/ServiceUnavailable.yaml'
@@ -138,3 +138,5 @@ responses:
     $ref: '../responses/TooManyRequests.yaml'
   '500':
     $ref: '../responses/InternalServerError.yaml'
+  '503':
+    $ref: '../responses/ServiceUnavailable.yaml'
@@ -102,3 +102,5 @@ responses:
     $ref: '../responses/TooManyRequests.yaml'
   '500':
     $ref: '../responses/InternalServerError.yaml'
+  '503':
+    $ref: '../responses/ServiceUnavailable.yaml'
@@ -73,3 +73,5 @@ responses:
     $ref: '../responses/TooManyRequests.yaml'
   '500':
     $ref: '../responses/InternalServerError.yaml'
+  '503':
+    $ref: '../responses/ServiceUnavailable.yaml'
@@ -180,3 +180,5 @@ responses:
     $ref: '../responses/TooManyRequests.yaml'
   '500':
     $ref: '../responses/InternalServerError.yaml'
+  '503':
+    $ref: '../responses/ServiceUnavailable.yaml'
@@ -87,3 +87,5 @@ responses:
     $ref: '../responses/TooManyRequests.yaml'
   '500':
     $ref: '../responses/InternalServerError.yaml'
+  '503':
+    $ref: '../responses/ServiceUnavailable.yaml'
@@ -111,3 +111,5 @@ responses:
     $ref: '../responses/TooManyRequests.yaml'
   '500':
     $ref: '../responses/InternalServerError.yaml'
+  '503':
+    $ref: '../responses/ServiceUnavailable.yaml'