Merge pull request #2076 from NHSDigital/feature/ERSSUP-81706

nhsd-jack-wainwright · web-flow · commit 43cbdd2cc025 · 2025-03-28T17:49:15.000Z
Feature/erssup 81706
diff --git a/sandbox/src/mocks/r4/NHSDigital-OperationOutcome-503.json b/sandbox/src/mocks/r4/NHSDigital-OperationOutcome-503.json
@@ -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"
+            }
+          ]
+        }
+      }
+    ]
+  }
+  
diff --git a/sandbox/src/mocks/stu3/STU3-ServiceUnavailable.json b/sandbox/src/mocks/stu3/STU3-ServiceUnavailable.json
@@ -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"
+            }
+          ]
+        }
+      }
+    ]
+  }
diff --git a/specification/components/r4/schemas/endpoints/a030-retrieve-business-functions.yaml b/specification/components/r4/schemas/endpoints/a030-retrieve-business-functions.yaml
@@ -111,3 +111,5 @@ responses:
     $ref: '../responses/TooManyRequests.yaml'
   '500':
     $ref: '../responses/InternalServerError.yaml'
+  '503':
+    $ref: '../responses/ServiceUnavailable.yaml'
diff --git a/specification/components/r4/schemas/endpoints/a033-retrieve-healthcare-service.yaml b/specification/components/r4/schemas/endpoints/a033-retrieve-healthcare-service.yaml
@@ -67,3 +67,5 @@ responses:
     $ref: '../responses/TooManyRequests.yaml'
   '500':
     $ref: '../responses/InternalServerError.yaml'
+  '503':
+    $ref: '../responses/ServiceUnavailable.yaml'
diff --git a/specification/components/r4/schemas/endpoints/a035-search-for-healthcare-services.yaml b/specification/components/r4/schemas/endpoints/a035-search-for-healthcare-services.yaml
@@ -77,3 +77,5 @@ responses:
     $ref: '../responses/TooManyRequests.yaml'
   '500':
     $ref: '../responses/InternalServerError.yaml'
+  '503':
+    $ref: '../responses/ServiceUnavailable.yaml'
diff --git a/specification/components/r4/schemas/endpoints/a037-retrieve-healthcare-service-version.yaml b/specification/components/r4/schemas/endpoints/a037-retrieve-healthcare-service-version.yaml
@@ -64,3 +64,5 @@ responses:
     $ref: '../responses/TooManyRequests.yaml'
   '500':
     $ref: '../responses/InternalServerError.yaml'
+  '503':
+    $ref: '../responses/ServiceUnavailable.yaml'
diff --git a/specification/components/r4/schemas/endpoints/a040-retrieve-practitioner-info.yaml b/specification/components/r4/schemas/endpoints/a040-retrieve-practitioner-info.yaml
@@ -55,3 +55,5 @@
           $ref: '../responses/TooManyRequests.yaml'
         '500':
           $ref: '../responses/InternalServerError.yaml'
+        '503':
+          $ref: '../responses/ServiceUnavailable.yaml'
diff --git a/specification/components/r4/schemas/endpoints/a041-search-service-request.yaml b/specification/components/r4/schemas/endpoints/a041-search-service-request.yaml
@@ -79,3 +79,5 @@ responses:
     $ref: '../responses/TooManyRequests.yaml'
   '500':
     $ref: '../responses/InternalServerError.yaml'
+  '503':
+    $ref: '../responses/ServiceUnavailable.yaml'
diff --git a/specification/components/r4/schemas/endpoints/a042-retrieve-attachment.yaml b/specification/components/r4/schemas/endpoints/a042-retrieve-attachment.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'
diff --git a/specification/components/r4/schemas/headers/response/RetryAfter.yaml b/specification/components/r4/schemas/headers/response/RetryAfter.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'
diff --git a/specification/components/r4/schemas/responses/ServiceUnavailable.yaml b/specification/components/r4/schemas/responses/ServiceUnavailable.yaml
@@ -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' 
diff --git a/specification/components/stu3/schemas/endpoints/a004-retrieve-reference-data.yaml b/specification/components/stu3/schemas/endpoints/a004-retrieve-reference-data.yaml
@@ -93,3 +93,5 @@ responses:
     $ref: '../responses/TooManyRequests.yaml'
   '500':
     $ref: '../responses/InternalServerError.yaml'
+  '503':
+    $ref: '../responses/ServiceUnavailable.yaml'
diff --git a/specification/components/stu3/schemas/endpoints/a005-retrieve-referral-request-versioned.yaml b/specification/components/stu3/schemas/endpoints/a005-retrieve-referral-request-versioned.yaml
@@ -90,3 +90,5 @@ responses:
     $ref: '../responses/TooManyRequests.yaml'
   '500':
     $ref: '../responses/InternalServerError.yaml'
+  '503':
+    $ref: '../responses/ServiceUnavailable.yaml'
diff --git a/specification/components/stu3/schemas/endpoints/a005-retrieve-referral-request.yaml b/specification/components/stu3/schemas/endpoints/a005-retrieve-referral-request.yaml
@@ -138,3 +138,5 @@ responses:
     $ref: '../responses/TooManyRequests.yaml'
   '500':
     $ref: '../responses/InternalServerError.yaml'
+  '503':
+    $ref: '../responses/ServiceUnavailable.yaml'
diff --git a/specification/components/stu3/schemas/endpoints/a006-retrieve-attachment.yaml b/specification/components/stu3/schemas/endpoints/a006-retrieve-attachment.yaml
@@ -102,3 +102,5 @@ responses:
     $ref: '../responses/TooManyRequests.yaml'
   '500':
     $ref: '../responses/InternalServerError.yaml'
+  '503':
+    $ref: '../responses/ServiceUnavailable.yaml'
diff --git a/specification/components/stu3/schemas/endpoints/a007-retrieve-clinical-information.yaml b/specification/components/stu3/schemas/endpoints/a007-retrieve-clinical-information.yaml
@@ -73,3 +73,5 @@ responses:
     $ref: '../responses/TooManyRequests.yaml'
   '500':
     $ref: '../responses/InternalServerError.yaml'
+  '503':
+    $ref: '../responses/ServiceUnavailable.yaml'
diff --git a/specification/components/stu3/schemas/endpoints/a008-retrieve-worklist.yaml b/specification/components/stu3/schemas/endpoints/a008-retrieve-worklist.yaml
@@ -180,3 +180,5 @@ responses:
     $ref: '../responses/TooManyRequests.yaml'
   '500':
     $ref: '../responses/InternalServerError.yaml'
+  '503':
+    $ref: '../responses/ServiceUnavailable.yaml'
diff --git a/specification/components/stu3/schemas/endpoints/a010-patient-service-search.yaml b/specification/components/stu3/schemas/endpoints/a010-patient-service-search.yaml
@@ -87,3 +87,5 @@ responses:
     $ref: '../responses/TooManyRequests.yaml'
   '500':
     $ref: '../responses/InternalServerError.yaml'
+  '503':
+    $ref: '../responses/ServiceUnavailable.yaml'
diff --git a/specification/components/stu3/schemas/endpoints/a011-create-referral.yaml b/specification/components/stu3/schemas/endpoints/a011-create-referral.yaml
@@ -111,3 +111,5 @@ responses:
     $ref: '../responses/TooManyRequests.yaml'
   '500':
     $ref: '../responses/InternalServerError.yaml'
+  '503':
+    $ref: '../responses/ServiceUnavailable.yaml'
diff --git a/specification/components/stu3/schemas/endpoints/a012-maintain-referral-letter.yaml b/specification/components/stu3/schemas/endpoints/a012-maintain-referral-letter.yaml
@@ -144,3 +144,5 @@ responses:
     $ref: '../responses/TooManyRequests.yaml'
   '500':
     $ref: '../responses/InternalServerError.yaml'
+  '503':
+    $ref: '../responses/ServiceUnavailable.yaml'
diff --git a/specification/components/stu3/schemas/endpoints/a013-accept-referral.yaml b/specification/components/stu3/schemas/endpoints/a013-accept-referral.yaml
@@ -72,3 +72,5 @@ responses:
     $ref: '../responses/TooManyRequests.yaml'
   '500':
     $ref: '../responses/InternalServerError.yaml'
+  '503':
+    $ref: '../responses/ServiceUnavailable.yaml'
diff --git a/specification/components/stu3/schemas/endpoints/a014-reject-referral.yaml b/specification/components/stu3/schemas/endpoints/a014-reject-referral.yaml
@@ -99,5 +99,7 @@ responses:
     $ref: '../responses/TooManyRequests.yaml'
   '500':
     $ref: '../responses/InternalServerError.yaml' 
+  '503':
+    $ref: '../responses/ServiceUnavailable.yaml'
   '504':
     $ref: '../responses/rejectReferral/504Response.yaml'
diff --git a/specification/components/stu3/schemas/endpoints/a015-retrieve-appointment-slots.yaml b/specification/components/stu3/schemas/endpoints/a015-retrieve-appointment-slots.yaml
@@ -80,3 +80,5 @@ responses:
     $ref: '../responses/TooManyRequests.yaml'
   '500':
     $ref: '../responses/InternalServerError.yaml'
+  '503':
+    $ref: '../responses/ServiceUnavailable.yaml'
diff --git a/specification/components/stu3/schemas/endpoints/a016-book-or-defer-appointment.yaml b/specification/components/stu3/schemas/endpoints/a016-book-or-defer-appointment.yaml
@@ -106,6 +106,8 @@ responses:
   '500':
     $ref: '../responses/InternalServerError.yaml'
   '502':
-    $ref: '../responses/bookOrDeferAppointment/502Response.yaml'      
+    $ref: '../responses/bookOrDeferAppointment/502Response.yaml'
+  '503':
+    $ref: '../responses/ServiceUnavailable.yaml'
   '504':
     $ref: '../responses/bookOrDeferAppointment/504Response.yaml'
diff --git a/specification/components/stu3/schemas/endpoints/a019-generate-patient-letter.yaml b/specification/components/stu3/schemas/endpoints/a019-generate-patient-letter.yaml
@@ -52,3 +52,5 @@ responses:
     $ref: '../responses/TooManyRequests.yaml'
   '500':
     $ref: '../responses/InternalServerError.yaml'
+  '503':
+    $ref: '../responses/ServiceUnavailable.yaml'
diff --git a/specification/components/stu3/schemas/endpoints/a020-upload-file-to-document-store.yaml b/specification/components/stu3/schemas/endpoints/a020-upload-file-to-document-store.yaml
@@ -99,3 +99,5 @@ responses:
     $ref: '../responses/TooManyRequests.yaml'
   '500':
     $ref: '../responses/InternalServerError.yaml'
+  '503':
+    $ref: '../responses/ServiceUnavailable.yaml'
diff --git a/specification/components/stu3/schemas/endpoints/a021-create-referral-request-and-send-for-triage.yaml b/specification/components/stu3/schemas/endpoints/a021-create-referral-request-and-send-for-triage.yaml
@@ -82,3 +82,5 @@ responses:
     $ref: '../responses/TooManyRequests.yaml'
   '500':
     $ref: '../responses/InternalServerError.yaml'
+  '503':
+    $ref: '../responses/ServiceUnavailable.yaml'
diff --git a/specification/components/stu3/schemas/endpoints/a022-cancel-appointment-action-later.yaml b/specification/components/stu3/schemas/endpoints/a022-cancel-appointment-action-later.yaml
@@ -109,3 +109,5 @@ responses:
     $ref: '../responses/TooManyRequests.yaml'
   '500':
     $ref: '../responses/InternalServerError.yaml'
+  '503':
+    $ref: '../responses/ServiceUnavailable.yaml'
diff --git a/specification/components/stu3/schemas/endpoints/a023-retrieve-a&g-worklist.yaml b/specification/components/stu3/schemas/endpoints/a023-retrieve-a&g-worklist.yaml
@@ -79,3 +79,5 @@ responses:
     $ref: '../responses/TooManyRequests.yaml'
   '500':
     $ref: '../responses/InternalServerError.yaml'
+  '503':
+    $ref: '../responses/ServiceUnavailable.yaml'
diff --git a/specification/components/stu3/schemas/endpoints/a024-retrieve-advice-and-guidance-versioned.yaml b/specification/components/stu3/schemas/endpoints/a024-retrieve-advice-and-guidance-versioned.yaml
@@ -67,3 +67,5 @@ responses:
     $ref: '../responses/TooManyRequests.yaml'
   '500':
     $ref: '../responses/InternalServerError.yaml'
+  '503':
+    $ref: '../responses/ServiceUnavailable.yaml'
diff --git a/specification/components/stu3/schemas/endpoints/a024-retrieve-advice-and-guidance.yaml b/specification/components/stu3/schemas/endpoints/a024-retrieve-advice-and-guidance.yaml
@@ -109,3 +109,5 @@ responses:
     $ref: '../responses/TooManyRequests.yaml'
   '500':
     $ref: '../responses/InternalServerError.yaml'
+  '503':
+    $ref: '../responses/ServiceUnavailable.yaml'
diff --git a/specification/components/stu3/schemas/endpoints/a025-retrieve-advice-and-guidance-conversation.yaml b/specification/components/stu3/schemas/endpoints/a025-retrieve-advice-and-guidance-conversation.yaml
@@ -116,3 +116,5 @@ responses:
     $ref: '../responses/TooManyRequests.yaml'
   '500':
     $ref: '../responses/InternalServerError.yaml'
+  '503':
+    $ref: '../responses/ServiceUnavailable.yaml'
diff --git a/specification/components/stu3/schemas/endpoints/a026-send-a&g-response.yaml b/specification/components/stu3/schemas/endpoints/a026-send-a&g-response.yaml
@@ -107,3 +107,5 @@ responses:
     $ref: '../responses/TooManyRequests.yaml'
   '500':
     $ref: '../responses/InternalServerError.yaml'
+  '503':
+    $ref: '../responses/ServiceUnavailable.yaml'
diff --git a/specification/components/stu3/schemas/endpoints/a027-convert-a&g-to-referral.yaml b/specification/components/stu3/schemas/endpoints/a027-convert-a&g-to-referral.yaml
@@ -112,3 +112,5 @@ responses:
     $ref: '../responses/TooManyRequests.yaml'
   '500':
     $ref: '../responses/InternalServerError.yaml'
+  '503':
+    $ref: '../responses/ServiceUnavailable.yaml'
diff --git a/specification/components/stu3/schemas/endpoints/a028-record-triage-outcome.yaml b/specification/components/stu3/schemas/endpoints/a028-record-triage-outcome.yaml
@@ -133,3 +133,5 @@ responses:
     $ref: '../responses/TooManyRequests.yaml'
   '500':
     $ref: '../responses/InternalServerError.yaml'
+  '503':
+    $ref: '../responses/ServiceUnavailable.yaml'
diff --git a/specification/components/stu3/schemas/endpoints/a029-available-actions-for-user-list.yaml b/specification/components/stu3/schemas/endpoints/a029-available-actions-for-user-list.yaml
@@ -97,3 +97,5 @@ responses:
     $ref: '../responses/TooManyRequests.yaml'
   '500':
     $ref: '../responses/InternalServerError.yaml'
+  '503':
+    $ref: '../responses/ServiceUnavailable.yaml'
diff --git a/specification/components/stu3/schemas/endpoints/a031-change-shortlist.yaml b/specification/components/stu3/schemas/endpoints/a031-change-shortlist.yaml
@@ -120,3 +120,5 @@ responses:
     $ref: '../responses/TooManyRequests.yaml'
   '500':
     $ref: '../responses/InternalServerError.yaml'
+  '503':
+    $ref: '../responses/ServiceUnavailable.yaml'
diff --git a/specification/components/stu3/schemas/endpoints/a032-change-shortlist-and-send-for-triage.yaml b/specification/components/stu3/schemas/endpoints/a032-change-shortlist-and-send-for-triage.yaml
@@ -100,3 +100,5 @@ responses:
     $ref: '../responses/TooManyRequests.yaml'
   '500':
     $ref: '../responses/InternalServerError.yaml'
+  '503':
+    $ref: '../responses/ServiceUnavailable.yaml'
diff --git a/specification/components/stu3/schemas/endpoints/a034-update-appointment.yaml b/specification/components/stu3/schemas/endpoints/a034-update-appointment.yaml
@@ -112,5 +112,7 @@ responses:
     $ref: '../responses/InternalServerError.yaml'
   '502':
     $ref: '../responses/updateAppointment/502Response.yaml'
+  '503':
+    $ref: '../responses/ServiceUnavailable.yaml'
   '504':
     $ref: '../responses/updateAppointment/504Response.yaml'
diff --git a/specification/components/stu3/schemas/endpoints/a036-cancel-referral.yaml b/specification/components/stu3/schemas/endpoints/a036-cancel-referral.yaml
@@ -163,5 +163,7 @@ responses:
     $ref: '../responses/InternalServerError.yaml'
   '502':
     $ref: '../responses/cancelReferral/502Response.yaml'
+  '503':
+    $ref: '../responses/ServiceUnavailable.yaml'
   '504':
     $ref: '../responses/cancelReferral/504Response.yaml'
diff --git a/specification/components/stu3/schemas/endpoints/a038-retrieve-appointment-versioned.yaml b/specification/components/stu3/schemas/endpoints/a038-retrieve-appointment-versioned.yaml
@@ -68,3 +68,5 @@ responses:
     $ref: '../responses/TooManyRequests.yaml'
   '500':
     $ref: '../responses/InternalServerError.yaml'
+  '503':
+    $ref: '../responses/ServiceUnavailable.yaml'
diff --git a/specification/components/stu3/schemas/endpoints/a038-retrieve-appointment.yaml b/specification/components/stu3/schemas/endpoints/a038-retrieve-appointment.yaml
@@ -109,3 +109,5 @@ responses:
     $ref: '../responses/TooManyRequests.yaml'
   '500':
     $ref: '../responses/InternalServerError.yaml'
+  '503':
+    $ref: '../responses/ServiceUnavailable.yaml'
diff --git a/specification/components/stu3/schemas/endpoints/a043-retrieve-advice-and-guidance-overview-pdf.yaml b/specification/components/stu3/schemas/endpoints/a043-retrieve-advice-and-guidance-overview-pdf.yaml
@@ -82,3 +82,5 @@ responses:
     $ref: '../responses/TooManyRequests.yaml'
   '500':
     $ref: '../responses/InternalServerError.yaml'
+  '503':
+    $ref: '../responses/ServiceUnavailable.yaml'
diff --git a/specification/components/stu3/schemas/endpoints/a044-create-advice-and-guidance-request.yaml b/specification/components/stu3/schemas/endpoints/a044-create-advice-and-guidance-request.yaml
@@ -94,3 +94,5 @@ responses:
     $ref: '../responses/TooManyRequests.yaml'
   '500':
     $ref: '../responses/InternalServerError.yaml'
+  '503':
+    $ref: '../responses/ServiceUnavailable.yaml'
diff --git a/specification/components/stu3/schemas/headers/response/RetryAfter.yaml b/specification/components/stu3/schemas/headers/response/RetryAfter.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'
diff --git a/specification/components/stu3/schemas/responses/ServiceUnavailable.yaml b/specification/components/stu3/schemas/responses/ServiceUnavailable.yaml
@@ -0,0 +1,23 @@
+description: |
+  Where status code 503 (Service Unavailable) is returned then an eRS-OperationOutcome-1 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.
+  
+  | Error code                         | Description                                                                                                                          |
+  | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+  | SYSTEM_UNAVAILABLE                 | 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: '../STU3-OperationOutcome.yaml'
+    example:
+      $ref: '../../examples/STU3-ServiceUnavailable.json'
diff --git a/specification/components/stu3/schemas/responses/bookOrDeferAppointment/504Response.yaml b/specification/components/stu3/schemas/responses/bookOrDeferAppointment/504Response.yaml
@@ -1,6 +1,7 @@
 description: |
   Where status code 504 (Gateway Timeout) is returned then an eRS-OperationOutcome-1 will be included in the body. 
   Check diagnostics property for specific information regarding the error.
+  In response to receiving this status code, it is recommended that clients retry at a later time.
 
   | Error code                         | Description                                                                                                                  |
   | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
diff --git a/specification/components/stu3/schemas/responses/cancelReferral/504Response.yaml b/specification/components/stu3/schemas/responses/cancelReferral/504Response.yaml
@@ -1,6 +1,7 @@
 description: |
   Where status code 504 (Gateway Timeout) is returned then an eRS-OperationOutcome-1 will be included in the body. 
   Check diagnostics property for specific information regarding the error.
+  In response to receiving this status code, it is recommended that clients retry at a later time.
 
   | Error code                         | Description                                                                                                                  |
   | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
diff --git a/specification/components/stu3/schemas/responses/rejectReferral/504Response.yaml b/specification/components/stu3/schemas/responses/rejectReferral/504Response.yaml
@@ -1,6 +1,7 @@
 description: |
   Where status code 504 (Gateway Timeout) is returned then an eRS-OperationOutcome-1 will be included in the body. 
   Check diagnostics property for specific information regarding the error.
+  In response to receiving this status code, it is recommended that clients retry at a later time.
 
   | Error code                         | Description                                                                                                                  |
   | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
diff --git a/specification/components/stu3/schemas/responses/updateAppointment/504Response.yaml b/specification/components/stu3/schemas/responses/updateAppointment/504Response.yaml
@@ -1,6 +1,7 @@
 description: |
   Where status code 504 (Gateway Timeout) is returned then an eRS-OperationOutcome-1 will be included in the body. 
   Check diagnostics property for specific information regarding the error.
+  In response to receiving this status code, it is recommended that clients retry at a later time.
 
   | Error code                         | Description                                                                                                                  |
   | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
