HTTP Status Codes
The HTTP status codes returned in the response aid applications in understanding whether a search was successful, and if not successful, provides some context as to why the search did not return the expected response.
These status codes are considered the base status codes that should be present in any implementing API. Implementations and guides may include additional status codes that their service supports and may supply further details on the circumstances or expected client behavior.
Error
If the search fails (cannot be executed, not that there are no matches), the return value return value SHALL be a status code 4xx (client error) or 5xx (API/service error). An OperationOutcome SHOULD be returned detailing the error.
| Scenario | HTTP Status Code | Outcome |
|---|---|---|
| The request is performed with incorrect syntax or against a resource or search parameter that the API does not currently support. | HTTP 400 Bad Request | Error code is returned in the response with an OperationOutcome detailing the error |
| The request is performed by an application that has not properly authenticated. | HTTP 401 Unauthorized | Error code is returned in the response with an OperationOutcome detailing the error |
| The request is performed by an authenticated user, but the authenticated user is not permitted to perform the requested operation. | HTTP 403 Forbidden | Error code is returned in the response with an OperationOutcome detailing the error |
| The request is performed on a resource type that is not supported | HTTP 404 Not Found | Error code is returned in the response with an OperationOutcome detailing the error |
| The request is performed using an HTTP method that the server does not support for the resource. | HTTP 405 Method Not Allowed | Error code is returned in the response with an OperationOutcome detailing the error |
| The request includes a media type which is not supported. For example, the client uploads an image as image/svg+xml, but the server requires that images use a different format. | 415 Unsupported Media Type | Error code is returned in the response with an OperationOutcome detailing the error |
| The request is performed but the server encountered an internal error during the process of the response message. | 500 Internal Server Error | Error code is returned in the response with an OperationOutcome detailing the error |
| The request is made when the service is temporarily unavailable. | 503 Service Unavailable | Error code is returned in the response with an OperationOutcome detailing the error |
| The request is performed but the server, while acting as a gateway or proxy, does not get a response in time from an upstream server in order to complete the request. | 504 Gateway Timeout | Error code is returned in the response with an OperationOutcome detailing the error |
Success
If the search is properly formatted and succeeds, the API SHALL return an HTTP 200 OK status code and the return content SHALL be a Bundle with type = searchset containing the results of the search as a collection of zero* or more resources in a defined order.
NOTE: Searches that are properly performed but have no PHI to return will still result in a HTTP 200 OK status code
| Scenario | HTTP Status Code | Outcome |
|---|---|---|
| The request is performed with correct syntax and there are FHIR resources available that match those search parameters | HTTP 200 OK | Success code is returned in the response, Bundle returned in the response contains entries with requested FHIR resources |
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 regardless of whether the submitted content is XML or JSON.