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.

Please refer to FHIR R4 RESTful API and associated sections for more detail.

2xx HTTP Success

In general, ff 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.

4xx/5xx HTTP Errors

In general, ff 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.

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.