Capability Statement > Response Handling

Response Handling

In FHIR, errors can be detected and processed at two different layers - the HTTP layer and the FHIR layer. HTTP errors are returned in the HTTP response code that is part of the HTTP specification. FHIR errors and warnings are returned using the OperationOutcome resource. In some cases, both may be present. This page provides some general guidance around the types of error handling behavior client systems should expect from SERIS.

HTTP Status Codes

The following table lists the HTTP codes that may come back from an HTTP call, the type of circumstances when such a response might occur, whether an OperationOutcome may or must be present (and what it will contain) and the general sort of behavior that the client system should execute.

Code Circumstances OperationOutcome? Client Expected Behavior
200 OK Indicates the submitted request was successful. In certain circumstances (e.g. when a consent block is in place) the request will not return the requested resource but will instead return an OperationOutcome indicating the reason the request wasn't completed. Yes Varies based on the specific request
201 Created Indicates the submitted resource was accepted. No Display a message to the user indicating the resource was successfully submitted.
400 Bad Request This indicates that the submitted request is invalid. For example, the URL is malformed, the query parameters are badly formatted or do not match the required data type. Typically, this indicates an error with the software design of the client system, but in cases where the client does not validate inputs (e.g. dates) before submission, it is possible that allowing the user to correct search parameters could result in a successful response. Yes Display the message associated with the OperationOutcome to the user and also provide information for how to contact system support for the client software. The OperationOutcome.issue.diagnostics and location should be made available as well.
401 Unauthorized Indicates the request has been made without the appropriate authorization token. This should only occur if the authorization token in use has expired - as no system should make a query without having an authorization token in place. No The client system should re-authenticate and re-transmit the request once a new token is received
403 Forbidden The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource, or may need an account of some sort No Information allowing the user to contact support for their Client system should be displayed and they should be able to cancel out of the process
404 Not found This will only be returned in the event of a specified resource does not exist. No Information allowing the user to contact support for their Client system should be displayed and they should be able to cancel out of the process
405 Method Not Allowed A request method is not supported for the requested resource; for example, a GET request on a form that requires data to be presented via POST, or a PUT request on a read-only resource. No Information allowing the user to contact support for their Client system should be displayed and they should be able to cancel out of the process
415 Unsupported Media Type The request entity has a media type which the server or resource does not support. For example, the client uploads an image as image/svg+xml, but the server requires that images use a different format. No Information allowing the user to contact support for their Client system should be displayed and they should be able to cancel out of the process
500 Internal Server Error Indicates that the server encountered an Internal error during the process of response message Yes
503 Service Unavailable Indicates that the services has been temporarily taken down (on purpose) Yes The OperationOutcome message should be displayed to the user indicating when they should expect to be able to successfully retry the request and be able to cancel out. There's no need to expose system support information
504 Gateway Timeout Indicates that one server did not receive a timely response from another server that it was accessing while attempting to load the web page or fill another request by the browser. No


Operation Outcome

OperationOutcome is used to provide more detailed description of any issues that occurred during execution of an operation. The general conventions for OperationOutcome are:

  • OperationOutcome can either be the sole response to an operation (generally accompanying an HTTP code that indicates a failure) or it can be part of a Bundle indicating potential warnings associated with the generation of the search response.

  • If an OperationOutcome is returned with anything other than a success (200), the issues it contains will be of type 'error' or 'fatal'. Fatal is used for issues that occur before the query can be exercised, 'error' is used for issues that occur during query execution.

  • OperationOutcomes returned as part of a Bundle will only contain 'warning' and 'information' messages. The user should always be made aware of the existence of these messages and the user should have the opportunity to review all such messages

  • The OperationOutcome.issue.code provides a standardized description of the issue. Systems MAY create logic based on the specific code returned

  • The details of the issue or warning will be found in issue.details.text. This content should always be displayed to the user

  • The issue.details.coding values, issue.diagnostics and issue.location are intended for diagnostic purposes and will generally only be relevant to help-desk personnel. It may be appropriate to make access to this information available only by clicking on a button rather than displaying information to the user that may be confusing

  • issue.location will only occur if the problem is with a submitted FHIR instance (i.e. it will not be present if the issue is for query parameters, HTTP headers, etc.) It will be expressed as an XPath.