Improved Error Messaging

We have released an update to the Ribbon API that includes significant improvements to our error messaging, both in terms of consistency and content.

To access this version (2019-10-28) add the following to your API request header:

Ribbon-Version: 2019-10-28

For example:

curl -X GET \
  https://api.ribbonhealth.com/v1/custom/providers/1234567890 \
  -H 'Authorization: Token {insert token here}' \
  -H 'Ribbon-Version: 2019-10-28' \

🚧

Add Ribbon-Version: 2019-10-28 to every request header or email [email protected]

After you complete testing with the updated version, feel free to let us know and will set your entire API to this version. Email us at [email protected]

Alternatively, you can add Ribbon-Version: 2019-10-28 to every request header.

Note: a user interface to toggle API versions is in the works!

New Error Messaging Structure

Our new error messaging will abide by the following structure:

{
  "error": {
    "status": 404,
    "code": "not_found",
    "message": "resource not found"
  }
}

🚧

Build logic on the status and code fields

If you are building logic around the Ribbon API's error messages, we recommend leveraging the status and code fields, as opposed to the message field which may be dynamic.

Note that the code and message fields are not intended to be displayed as-is in a customer-facing UI.

List of Ribbon Error Codes

Bad Request (400)

  • bad_request
  • invalid_npi

Unauthorized (401)

  • authentication_failed

Forbidden (403)

  • permission_denied

Not Found (404)

  • not_found

Conflict (409)

  • conflict - resource already exists

Too Many Requests (429)

  • rate_limit_exceeded

Internal Server Error (500)

  • internal_server_error