Toggle Sidebar

Response Codes

HTTP Reponse Codes

The ClearOS API uses conventional HTTP response codes for error handling.

Code Response Description
200 OK Request was successful
400 Bad Request The client request was invalid
401 Unauthorized The API key or credentials were invalid
403 Forbidden The API key or credentials were valid, but access was not permitted
404 Not Found The resource was not found
405 Method Not Allowed The method is not supported by the API
409 Conflict Resource already exists
422 Validation Error Parameters sent in the request were invalid
429 Too Many Requests Too many requests were sent to the server
500 Server Error Server-side error (rare)

Extended Response Codes

In addition to the HTTP response codes, a status code and message are also passed in the JSON payload. Here’s an example:

    "status_code": "400.111",
    "status_message": "Dynamic DNS account not enabled.",

The status_message provides a helpful one sentence description of the response.

The additional status_code is typically used by specific apps that need more than the limited set of available HTTP response codes. For example, the Dynamic DNS client uses several status codes to be compatible with other 3rd party Dynamic DNS clients. For the most part, you can use the standard HTTP response codes for error handling, but check the documentation on API endpoints if you want to handle extended errors in a different way.

Validation Handling

When a validation error occurs (HTTP Response code 422), the validation_details object is returned in the JSON payload. Here's an example:

    "status_code": "422.000",
    "status_message": "Validation error.",
    "validation_details": {
        "id": "System ID is invalid.",
        "name": "System name contains invalid characters."