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

Code

Name

Details

200

OK

Nothing. You can just go back sipping your coffee in your cushie Herman Miller.

400

Bad Request

Review your request body and parameters. You’ve probably missed something. See the detail property in the error message for more info.

401

Unauthorized

You failed to authenticate with the server. Check: Did your token expire?

403

Forbidden

You’re authenticated but you do not have permission to access the requested resource. Check: Are you using the right user or role?

404

Resource Not Found

The resource you requested does not exist.

422

Unprocessable Entity

The parameters provided could not be processed. Check the detail property in the error message for more info.

500

Internal Server Error

A 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.

503

Service Unavailable

May 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.


Did this page help you?