Handling errors

Requests made to the Capable Health API can result in several different responses. The following document provides a list of possible status code values in those responses and describes the structure of error responses. We also describe some common recovery tactics to use when receiving different error response codes.

HTTP Status Codes

Table with explanations of our HTTP response codes

CodeNameDetails
200OKNothing. You can just go back sipping your coffee in your cushie Herman Miller.
400Bad RequestReview your request body and parameters. You’ve probably missed something. See the detail property in the error message for more info.
401UnauthorizedYou failed to authenticate with the server. Check: Did your token expire?
403ForbiddenYou’re authenticated but you do not have permission to access the requested resource. Check: Are you using the right user or role?
404Resource Not FoundThe resource you requested does not exist.
422Unprocessable EntityThe parameters provided could not be processed. Check the detail property in the error message for more info.
500Internal Server ErrorA generic error occurred on the server. This may indicate a bug or service failure. Please reach out to us by reporting the issue here so that the Capable Health support team can look into the error ASAP.
503Service UnavailableMay indicate service failure or lack of availability. If you encounter this error code, please reach out to us by reporting the issue here so that the Capable Health support team can look into the error ASAP.

Error Responses

Capable Health errors follow the JSON:API spec when the response comes from any live endpoint. Please note that the structure will be different if you accidentally hit a non-existent endpoint. Our errors will always contain an errors array containing 1 or more error objects.

An error object will always contain the following properties:

  • title
  • detail

The following properties will only be present when relevant:

  • links
  • source

The following represents the structure of a common error response resulting from a failed API request:

{
    // Errors will always be an array of error objects
    "errors": [
        {
          "title": "An error message.",
          "links": {
              "about": "A link to our API spec for additional info"
          },
          "detail": "A detailed message describing why the param or property was not accepted",
        // The 'Source' property is optional and may not always be present.
          "source": {
              "pointer": "the/path/to/the/property",
              "parameter": "name_of_the_param_or_property"
            }
          }
        }
     ]
}

Error Messages

The following messages are example values for the title property of an error message. The title will be generic and correspond to the HTTP status codes. See the detail property in the error object for more info.

  • Your request parameters are invalid.
    • Some or all of your parameters are either missing or are invalid
  • Resource Not Found
    • The resource you requested could not be found with the ID provided

Others defined in the “HTTP Status Codes” section above are also possible.