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).
|
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 |
{ |
Permissions issue |
{ |
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 |
{ |
Invalid Data Type |
{ |
Duplicate Data |
{ |
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.
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.