Response Handling
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.
2xx HTTP 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 |
| The request is successful and a FHIR resource has been created on the server | HTTP 201 Created | Success code is returned in the response, the location of the resource is returned in the location header of the response |
4xx/5xx HTTP Client Errors
If the search fails (cannot be executed, not that there are no matches), the 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 been 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. | HTTP 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. | HTTP 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. | HTTP 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. | HTTP 504 Gateway Timeout | Error code is returned in the response with an OperationOutcome detailing the error |
The error responses SHOULD use the OperationOutcome resource to return both human-readable and machine-processing information with sufficient details to enable the requester to debug the error.