Amb-1491-spec-updates

specification/service-search-api.yaml

@@ -78,9 +78,6 @@ info:
 
     For more details see [integration testing with our RESTful APIs](https://digital.nhs.uk/developer/guides-and-documentation/testing#integration-testing-with-our-restful-apis).
 
-    ### Rate Limiting
-    The integration test environment is rate limited to 1500 requests per week and 1 request per second.
-
     ## Onboarding
     This API is not yet available for onboarding.
 
@@ -579,11 +576,57 @@ paths:
           $ref: "#/components/responses/NotFound"
         "429":
           $ref: "#/components/responses/TooManyRequests"
-        "500":
-          $ref: "#/components/responses/InternalServerError"
 
 components:
   responses:
+    4XX-SERVICE-SEARCH:
+      description: |
+        Below are examples of potential HTTP status codes and their associated error codes, which could be returned in the event of a fault. 
+        Guidance on error handling within the Booking and Referral Service can be found [here](https://simplifier.net/guide/nhsbookingandreferralstandard/Home/Design/Design--Core#Error-handling).
+
+        | HTTP status | Error code                 | Description |
+        | ----------- | -------------------------- | --------------------------------------------- |
+        | 400         | SEND_BAD_REQUEST           | The API was unable to process the request. |
+        | 400         | REC_BAD_REQUEST            | The Receiver has responded stating the message was malformed. |
+        | 401         | SEND_UNAUTHORIZED          | The API deemed you unauthorized to make this request. |
+        | 401         | REC_UNAUTHORIZED           | The receiver deemed you unauthorized to make request. |
+        | 403         | SEND_FORBIDDEN             | Missing or Expired Token. |
+        | 404         | PROXY_NOT_FOUND            | No related people exist for given NHS number. |
+        | 404         | REC_NOT_FOUND              | Patient record for given NHS number has been invalidated and not superseded by another NHS number. |
+        | 405         | SEND_METHOD_NOT_ALLOWED    | HTTP Verb is not correct for this scenario.|
+        | 405         | REC_METHOD_NOT_ALLOWED     | Receiver does not allow this.|
+        | 405         | PROXY_METHOD_NOT_ALLOWED   | Proxy does not allow this.|
+        | 406         | SEND_NOT_ACCEPTABLE        | Senders message had an incorrect content type defined for a response.|
+        | 408         | REC_TIMEOUT                | The downstream domain processing has not completed within the configured timeout period. |
+        | 409         | SEND_CONFLICT              |  |
+        | 409         | REC_CONFLICT               |  |
+        | 409         | PROXY_CONFLICT             |  |
+        | 422         | SEND_UNPROCESSABLE_ENTITY  | Message was not malformed but deemed unprocessable. |
+        | 422         | REC_UNPROCESSABLE_ENTITY   | Message was not malformed but deemed unprocessable. |         
+        | 422         | PROXY_UNPROCESSABLE_ENTITY | Message was not malformed but deemed unprocessable. |         
+        | 429         | SEND_TOO_MANY_REQUESTS     | The user has sent too many requests in a given amount of time|
+        | 429         | REC_TOO_MANY_REQUESTS      | The user has sent too many requests in a given amount of time|
+
+      content:
+        application/fhir+json:
+          schema:
+            $ref: '#/components/schemas/OperationalOutcome'
+          example:
+            $ref: examples/400-SEND.json
+      headers:
+        X-Correlation-Id:
+          description: 'The X-Correlation-Id from the request header, if supplied, mirrored back.'
+          schema:
+            type: string
+            format: uuid
+            example: 9562466f-c982-4bd5-bb0e-255e9f5e6689
+        X-Request-Id:
+          description: 'The X-Request-Id from the request header, if supplied, mirrored back.'
+          schema:
+            type: string
+            format: uuid
+            example: c1ab3fba-6bae-4ba4-b257-5a87c44d4a91
+
     BadRequest:
       description: Bad Request
       content:
@@ -677,14 +720,12 @@ components:
                       format: uri
 
     OrganisationTypeResults:
-      description: Organisation Type Search Results
+      description: Success
       content:
         "application/json":
           examples:
             OrganisationTypes:
               $ref: "examples/organisation-types_v1.json"
-            NotFound:
-              $ref: "examples/organisation-types-not-found_v1.json"
             SingleItem:
               $ref: "examples/organisation-types-single-item_v1.json"
           schema: