HTTP Responses

The responses returned by the BadgerNet Spine API indicate the success or failure of the request. Each response includes an HTTP Status Code which gives an overall indication of the result of the request. Generally, these are grouped into the following three categories:

Successful Responses (200 - 299)
Client Error Responses (400 - 499)
Server Error Responses (500 - 599)

Most requests to the API also return a payload in FHIR JSON format which includes one of the following structures:

The result of a query (e.g. a bundle of FHIR resources)
An Operation Outcome resource containing a list of errors and/or warnings.

Successful Responses

2xx-range status codes indicate that the request was successful, for example meaning that data was created or updated.

Status Code	Meaning	Description
`200`	`OK`	The request successfully retrieved data, and the result is included in the body of the response
`201`	`Created`	The request successfully created a new record. The location of the record is indicated in the response headers.
`204`	`No Content`	The request was successful (e.g. a record was updated). There isn’t a body included in the response.
`207`	`Multi-Status`	The request was successful, however some warning messages were generated which may require attention by the client. The body will include an Operation Outcome resource which includes the warnings.

Example 207 - Multi-status successful response including warnings:

JSON

{
    "resourceType": "OperationOutcome",
    "issue": [
        {
            "severity": "warning",
            "code": "informational",
            "diagnostics": "Observation raised the following warning: 'An example warning, which the client should inspect to determine if action is required'."
        }
    ]
}

Client Error Responses

4xx-range status codes indicate that the request was unsuccessful due to an error at the client side of the request. In many cases, the client can resolve the issue and re-send the request again successfully.

Status Code	Meaning	Description
`400`	`Bad Request`	The request was malformed and could not be interpreted. For example, the FHIR format was not valid JSON.
`401`	`Unauthorized`	The request does not contain a valid access token, or the token has expired.
`403`	`Forbidden`	The client made a request for an endpoint or resource which is not allowed.
`404`	`Not Found`	The requested resource or endpoint does not exist
`405`	`Method Not Allowed`	The HTTP method in the request is not allowed for the specified endpoint. For example an attempt to `PUT` to an endpoint which only accepts `POST`.
`406`	`Not Acceptable`	The API cannot conform to the specified criteria sent by the client. For example, a request for data in an unsupported format.
`409`	`Conflict`	The request was unable to create a new record, since another record already exists with the same matching key details. Alternatively, this response is returned when the request was expected to match a single record, but multiple matches were found.
`422`	`Unprocessable Entity`	The client sent data which is valid FHIR, but does not conform to the business rules of the API. An Operation Outcome resource will be returned in the response body containing a list of errors (and potentially warnings) which should be inspected to determine the reason for failure.
`429`	`Too Many Requests`	The request was throttled by the API since too many requests were sent during the applicable timeframe.

Example 422 - Unprocessable Entity failure response:

JSON

{
    "resourceType": "OperationOutcome",
    "issue": [
        {
            "severity": "error",
            "code": "business-rule",
            "diagnostics": "A valid National ID with a valid Identifier System is missing in the Patient resource"
        }
    ]
}

Example 403 - Forbidden failure response (for privacy reasons):

JSON

{
    "resourceType": "OperationOutcome",
    "issue": [
        {
            "severity": "error",
            "code": "suppressed",
            "diagnostics": "Access to the record is restricted due to 'Do Not Share' preferences"
        }
    ]
}

Server Error Responses

5xx-range status codes indicate that the request was unsuccessful due to an error at the server side of the request. This may be due to a system failure, or scheduled downtime of the API. Usually, the request can be successfully retried after a short delay.

Status Code	Meaning	Description
`500`	`Internal Server Error`	The server received the request, however an internal bug or failure condition meant that it could not process it successfully.
`503`	`Service Unavailable`	The API is not currently available. This could indicate that the API is down for maintenance, or that a system failure is preventing the Spine from operating correctly.