Responses and Errors

The ClariNet LS Public API indicates the success or failure of a request by returning standard HTTP status codes (see https://en.wikipedia.org/wiki/List_of_HTTP_status_codes ). Successful responses are indicated with a 2xx status code. A response with a 4xx code generally indicates an error that can be addressed by the end user, such as authentication or parameters. A 5xx response is an unexpected response generated on the server and if this persists, you should contact ClearLife’s support for help.

The common codes generally returned by the API are listed below. Some endpoints might have further details on their respective documentation.

2xx Success

Code	Text	Description
200	OK	For GET requests, this is the standard response and the response body will typically contain the requested resource. For other requests, this indicates success, the response body or headers might contain further details.
201	Created	A new entity was created. For example, most of the reports created by the Import/Export end points will return this code, indicate that a new report is being created. Typically the header will contain a URL pointing to the newly created resource.
204	No Content	The request was successful but no further information is included in the body or headers.

4xx Client errors

Code	Text	Description	Resolution
400	Bad Request	The request is not correctly formed. The response body or headers might contain details about the failure. If the end point affects multiple entities (such as editing multiple Cases), this doesn't necessarily mean all the edits failed.
401	Unauthorized	API key is missing or invalid.	The API Keys names are listed on the ClariNet LS website for the relevant user under the User menu/Change Security Details. The values are only available when initially created. If the value is lost, a new Key must be created. ClearLife cannot retrieve lost keys.
403	Forbidden	The required Role is missing. Each endpoint shows the Role required to access it.	API Keys are mapped to Users. Ask the Client Administrator to ensure that the required Role is given to that User (via the Admin menu/Users).The user themselves can login to the ClariNet LS website and check the assigned Roles (but a User cannot modify their own Roles, only a Client Administrator).
429	Too many requests	Most endpoints limit the number of concurrent requests. This status code is returned when the threshold is exceeded. Unless otherwise specified, this is more than 1 request in 1 second.

Examples

json

// 400 Bad Request
[
    {
        "caseReference": "ExampleCase 1564078581",
        "errors": [
            "Case Reference already exists"
        ],
        "htmlErrorString": "Case Reference already exists"
    }
]