Articles in this section

Success and Failure Return Data

  • Updated

When a call is made to a PainChek API endpoint, you should always receive a JSON formatted response.  That response can be parsed to determine if a request has succeeded or not.

Successful Responses

Authentication Requests

Authentication requests to generate new tokens are successful if an "access_token" and a"refresh_token" item are returned:

{
  "access_token": "AREsPc6GDeqmPuVoM94q4f3WpMhAID",
  "refresh_token": "mBmsWqDeYtqJT0yXf9viXnZGcf0CsM",
  "other items": "..."
}

GET Requests

A GET request that is returning a list of data (multiple items), is successful if there's a "count" and a "results" object:

{
  "count":17,
  "results":[
     {"uuid":"object 1"},
     {"uuid":"object 2"},
     {"uuid":"..."},
     {"uuid":"object 17"}
  ]
}


A get request that is returning a single item of data is successful if there's a "uuid" object:

{
  "uuid":"fe540355-2356-4363-b84d-7f4cea093cf8",
  "other items": "..."
}

POST, PUT and PATCH Requests

A POST, PUT or PATCH is successful if there's a "uuid" object:

{
  "uuid":"fe540355-2356-4363-b84d-7f4cea093cf8",
  "other items": "..."
}

Failure Responses

The following is an example of a typical failure response:

{
    "code": "not_authenticated",
    "detail": "Authentication credentials were not provided.",
    "errors": [
        {
            "detail": "Authentication credentials were not provided."
        }
    ]
}

The following items can be found in a failure response:

Item
Type
Mandatory
Description
Example
detail text yes

A description of the error that would be used for display or logging purposes. 

Do not make decisions based on the value in this field as it is subject to change.

 Authentication credentials were not provided.
code text no

An optional code associated with the error.  If supplied, it is safe to make decisions based on this code (it will not change).

(info) Unfortunately, there is no master list of error codes and their descriptions available.

 not_authenticated
errors object yes

Holders more details on the error or errors that occurred.  The presence of an "errors" array in the returned JSON is a good indicator that there was a failure.

Each object in the array has an optional "field" item and a mandatory "detail" item.

 "errors": [ {
  "field": "gender",
  "detail": "This field is required."
  },{
  "field": "birth_date",
  "detail": "This field is required."
  }]
field text no Identifies the name of the field that caused the error birth_date

Token Errors

When generating a new token (either by supplying credentials or using a refresh token), if the supplied credentials are not valid, an "error" item is returned.  You may also receive an "error_description" item:

{
    "code": "invalid_grant",
    "detail": "Invalid credentials",
    "errors": [
        {
            "detail": "Invalid credentials"
        }
    ]
}

 

Common errors include:

  • "unsupported_grant_type" - Ensure the grant_type is "password" or "refresh_token"
  • "invalid_client" - Ensure "client_id" and "client_secret" are correct
  • "invalid_grant" - If the grant type is "password", ensure the "username" and "password" are correct and the user is an active user.  If the grant type is "refresh_token", ensure the "refresh_token" is valid and that the "client_id" is linked to that refresh token.

Authentication Errors

If a request is made using an invalid token (either because the token is not valid or it has expired), a "detail" record is returned.

{
    "detail": "Authentication credentials were not provided.",
    "errors": [
        {
            "detail": "Authentication credentials were not provided."
        }
    ],
    "code": "not_authenticated"
}

This error is not very specific and may arise due to:

a) Using an existent token

b) Using an expired token

c) Using an authentication method not supported by the PainChek API

Invalid Resources

If a request is trying to access an invalid resource (e.g. a non-existent patient or a resource they do not have rights to), a "detail" record is returned.

Example
Sample Return
Invalid Resource
{
    "detail": "Not found.",
    "errors": [
        {
            "detail": "Not found."
        }
    ]
}
Permissions issue
{
    "detail": "You do not have permission to perform this action.",
    "errors": [
        {
            "detail": "You do not have permission to perform this action."
        }
    ],
    "code": "permission_denied"
}

Invalid Data and Other Issues

The most common errors are those that arise due to data issues - e.g. a mandatory field not being supplied, a field is supplied with data that is not consistent with its' type or a new record results in a duplicate.  Unfortunately, no explicit error condition can be identified (as each error item is identified by the field name)  and all we can do here is provide some general guidance:

Example
Sample Return
Mandatory Field Missing
{
    "errors": [
        {
            "field": "gender",
            "detail": "This field is required."
        },
        {
            "field": "birth_date",
            "detail": "This field is required."
        }
    ],
    "detail": "gender: This field is required. birth_date: This field is required.",
    "code": "invalid"
}
Invalid Data Type
{
    "errors": [
        {
            "field": "birth_date",
            "detail": "Date has wrong format. Use one of these formats instead: YYYY[-MM[-DD]]."
        }
    ],
    "detail": "birth_date: Date has wrong format. Use one of these formats instead: YYYY[-MM[-DD]].",
    "code": "invalid"
}
Duplicate Data
{
    "errors": [
        {
            "field": "email",
            "detail": "A user with that email already exists."
        }
    ],
    "detail": "email: A user with that email already exists.",
    "code": "invalid"
}

 

In all cases, the field with the error is the name of JSON object and the data is an array of issues with that field.

General Principles

It is recommended that you look for a success indicator and, if found, process the response from the API and continue as per normal.  If that's not found, then you can use the failure responses to ensure the most informative error message is logged/displayed. 

(warning)  A process using the API must assume failure in the case that neither a success or failure message as documented above is received.  Please contact support@painchek.com if you observe a behaviour that is unexpected with the API.

Related articles