operationOutcome.yaml

type: object
description: |
  Outcome of an operation that does not result in a resource or bundle being returned (e.g. error, async/batch submission).
  There are a number of possible error codes that can be returned along with a more detailed description in the `display` field.
  
  There are general outcomes:
  
  | Code                       | Response Code | Description                                   |
  | -------------------------- | ------------- | --------------------------------------------- |
  | ACCESS_DENIED              | 401           | Used when the user does not have permission for a particular request. e.g. when their ASID does not have the correct interactions attached to it. |
  | FAILURE_TO_PROCESS_MESSAGE | 500           | A default message when something really bad has happened that the system could not handle.	|
  | UNABLE_TO_CALL_SERVICE     | 408           | For a synchronous request, the downstream domain processing has not completed within the configured timeout period. |
  | UNSUPPORTED_SERVICE        | 400           | The service the user requested is an endpoint that does not exist - so is unsupported. e.g. /Patient/9999999999/Pets |
  | RESOURCE_NOT_FOUND         | 404           | The resource was not found. |
  | INVALID_RESOURCE_ID        | 400           | The resource ID was not valid. For example a NHS Number is presented which is not a valid NHS Number. |
  | INVALIDATED_RESOURCE       | 404           | The resource has been invalidated so could not be returned. |
  
  Search outcomes:
  
  | Code                       | Response Code | Description                                   |
  | -------------------------- | ------------- | --------------------------------------------- |
  | INVALID_SEARCH_DATA	       | 400           | The search parameters are invalid. A description of what exactly is at fault will be added to the display. |
  | TOO_MANY_MATCHES           | 200           | Too many matches were found - user should be told to refine their search parameters.	|
  
  Update outcomes:
  
  | Code                       | Response Code | Description                                   |
  | -------------------------- | ------------- | --------------------------------------------- |
  | PRECONDITION_FAILED        | 412           | Request missing basic requirements such as If-Match header (or invalid headers). |
  | RESOURCE_VERSION_MISMATCH  | 409           | The resource version has changed since your last read, so the update has been rejected. |
  | FORBIDDEN_UPDATE           | 403           | The user is not permitted to update certain resources or elements - a detailed description will be added to the display. For example - updating a sensitive patient or adding a formal death notification is only permitted from certain systems. |
  | VALIDATION_ERROR           | 400           | This it the "default" error thrown when no others are applicable. |
  | INVALID_UPDATE             | 400           | The update was invalid - a detailed description will be added to the display. |
  | MISSING_VALUE              | 400           | There was a missing value in the request. For example - a name update that is missing the surname. The missing value will be presented in the display.	|
  | INVALID_VALUE              | 400           | There was an invalid value in the request. For example - a name update where the surname is too long. The invalid value and field will be presented in the display. |
  | UNSUPPORTED_VALUE          | 400           | There was an unsupported value in the request. The value may be valid in the schema - however it could be a legacy value that we do not allow to be set anymore. For example - setting the death notification status to 'removed'. The invalid value and field will be presented in the display. |
  | TOO_FEW_VALUES_SUBMITTED   | 400           | The field in question has a minimum number of items and the user sent too few. |
  | TOO_MANY_VALUES_SUBMITTED  | 400           | The field in question has a maximum number of items and the user sent too many. |
  | ADDITIONAL_PROPERTIES      | 400           | The user sent additional properties within the dictionary. For example sending a patient patch and attempting to add 'pets', which is not an allowed field within the patient resource. |
  
  Polling outcomes
  
  | Code                       | Response Code | Description                                   |
  | -------------------------- | ------------- | --------------------------------------------- |
  | POLLING_ID_NOT_FOUND       | 404           | When polling the ID was not found - or it was not applicable such as a non polling ID.	|
  | POLLING_MESSAGE_FAILURE    | 422           | When polling an ID, a message was found to be in a failed state, so there is nothing else to be done and should be considered a failure. |
properties:
  resourceType:
    type: string
    description: FHIR Resource Type.
    default: OperationOutcome
    readOnly: true
  issue:
    type: array
    description: List of issues that have occurred.
    minItems: 1
    items:
      type: object
      required:
        - severity
        - code
      properties:
        severity:
          type: string
          enum: [fatal, error, warning, information]
          description: Severity of the error.
          example: error
        code:
          type: string
          description: FHIR error code.
          example: invalid
          enum:
            - invalid
            - structure
            - required
            - value
            - invariant
            - security
            - login
            - unknown
            - expired
            - forbidden
            - suppressed
            - processing
            - not-supported
            - duplicate
            - multiple-matches
            - not-found
            - deleted
            - too-long
            - code-invalid
            - extension
            - too-costly
            - business-rule
            - conflict
            - transient
            - lock-error
            - no-store
            - exception
            - timeout
            - incomplete
            - throttled
            - informational
        details:
          $ref: https://gist.githubusercontent.com/artronics/dfd497d913d10184925169d562cd22f7/raw/017b4484e9d4215be9e2ac1f163450c0b9311c22/errorCode.yaml
        diagnostics:
          type: string
          description: Additional diagnostic information about the issue.
          example: Invalid value - 2019-01 in field 'birthDate'
        expression:
          type: string
          description: FHIRPath of element(s) related to the error.
          example: Patient.name.given