Responses

Possible Response Status Codes

The RoofLink Public API uses the standardized HTTP status codes to indicate the status of a request. All status codes in the 2xx range indicate a successful request, and 4xx and 5xx status codes are used to indicate errors.

The following status codes may be received when executing requests to these APIs:

Success Codes

Status Code	Description
200 - Ok	This status code is returned on normal execution of a request. It indicates that a request is successful and that the response body has content.
201 - Created	This status code is returned when a request is successfully executed, and the request resulted in the creation of a new object. In this case, the body will contain the ID of the newly created object as well as additional endpoint-specific data.
204 - No Content	This status code is returned when a request is successfully executed, and the response body does not contain any content. This is commonly used in delete requests.

Error Codes

Status Code	Description	Recommended Solution Steps
400 - Bad Request	This status code is returned when the server receives an invalid request, usually due to malformed path or query parameters.	Please check if the URL, all path, and query parameters are in the formats defined by the endpoint documentation.
401 - Unauthorized	This status code is returned when the server is unable to authenticate a user for the request execution.	Please check that the execute request follows the guidelines found in the Authentication Page and that your API Key is valid.
403 - Forbidden	This status code is returned when the authenticated user does not have the required permissions to execute a request.	Please check that the user associated with your API Key has the required permissions to execute the request.
404 - Not Found	This status code is returned when a matching endpoint is not found in the server, or a matching object is not found within the collection of objects accessible to the currently authenticated user.	Please ensure that the URL and path parameters sent in the request are correct. If the request includes object identifiers, please check that the user associated with your API Key has permissions to access these objects.
405 - Method Not Allowed	This status code is returned when the method used in the request execution is not available for a particular endpoint.	Please check the method, URL, and path parameters of the executed request.
429 - Too Many Requests	This status code is returned when a client exceeds the per-client rate limits of the API.	See the Introduction page for additional recommendations on how to handle this response.
500 - Internal Server Error	This status code is returned when an unexpected error occurs while processing a request.	Please check if the executed request is following the documentations for the endpoint. If the error persists, please report it to us via the RoofLink Support.
503 - Service Unavailable	This status code is returned when the total rate limits for the Public API are exceeded.	See the Introduction page for additional recommendations on how to handle this response.

Paginated Responses

All endpoints in the RoofLink public API designed to allow listing or searching of objects in a given collection will return paginated responses.

The paginated responses contain a JSON object, including the following fields:

Field	Type	Description
count	integer or null	Total number (across all pages) of elements matching the criteria specified in the request. This value will be set to `null` if the requested value in the `page` query parameter is invalid.
from_index	integer or null	Index of the first element included in the current page, starting from 1. This value will be set to `null` if the requested value in the `page` query parameter is invalid.
to_index	integer or null	Index of the last element included in the current page. This value will be set to 0 if no elements matching the request are found, and to `null` if the requested value in the `page` query parameter is invalid.
next	string or null	Absolute URL for the next page if one exists and `null` otherwise.
previous	string or null	Absolute URL for the previous page if one exists and `null` otherwise.
next_page	integer or null	Number of the next page if one exists and `null` otherwise.
results	array of objects	Array containing the data for the objects matching the requested criteria. Will be empty if no matching is found, and will contain at most the number of elements specified in the `page_size` parameter.

Response Examples

A request that results in no matching objects found will have the following format:

{
    "count": 0,
    "from_index": 1,
    "to_index": 0,
    "next": null,
    "previous": null,
    "next_page": null,
    "results": []
}

And requests with matching objects have the following response formats:

{
    "count": 10,
    "from_index": 1,
    "to_index": 5,
    "next": "https://integrate.rooflink.com/roof_link_endpoints/api/light/<endpoint>/?page=2&page_size=5",
    "previous": null,
    "next_page": 2,
    "results": [
        {
            ...
        },
        {
            ...
        },
        ...
    ]
}

{
    "count": 10,
    "from_index": 6,
    "to_index": 10,
    "next": null,
    "previous": "https://integrate.rooflink.com/roof_link_endpoints/api/light/<endpoint>/?page=1&page_size=1",
    "next_page": null,
    "results": [
        {
            ...
        },
        {
            ...
        },
        ...
    ]
}