Error Handling

With each API call you must verify the HTTP status code. Codes 200 and 204 indicate successful calls. Any other codes signify a failed call. Errors originating in the Beebox include a JSON object with error message and details. The message is meant to be "user friendly" and can be shown to the end user. List for status codes and their interpretation:

HTTP status code	Description
200	SUCCESS The API call was successful and includes a json formatted result according to the API documentation.
204	SUCCESS The API call was successful. The method does not return any results.
400	FAILED The API call failed. The http call returns a json which describes the error. The json document has these properties: { "type": Error category. You usually do not need to read this. "message": A user friendly error message. Designed to be readable by end users. It is recommended to show these errors to the end user (if applicable). "id": Some errors include an error identifier. Where used, ids are described with the API methods: BUSY: Returned when connecting and automatic operations are running so that a login is not possible. Try login again in a few seconds. LOGGEDOUT: You are not connected or had been disconnected. Other codes are explained in API method documentation where applicable. "inner": In some cases includes a more technical error description. You would not show this to the end users. "failed": Always set to "true". }
Other codes	FAILED There may be other http error codes returned. Other error codes that do not return a json object are low level errors likely due to the web server configuration and not the Beebox API itself. For example, a 404 error points to an inexistent API method.

EXAMPLE

This is the JSON result if you are not connected. HTTP status code is 400:

CODE

{
	"type":"Api error",
	"id":"LOGGEDOUT",
	"message":"Not authorised",
	"failed":true
}

If you call wrong API methods or with wrongly named parameters, then you get a status code 404 and a result which is formatted differently from what is described further up:

CODE

{
	"Message":"No HTTP resource was found that matches the request URI 'http://localhost:1781/api/details?token2=32b7cb0c-46ce-42ac-a4b8-6a4d04ef6089-Test'.",
	"MessageDetail":"No action was found on the controller 'ApiProject' that matches the request."
}

Such errors point to development errors.

WINDOWS EVENT LOG

Most errors are written to the Windows event log. You will find full error details there.

We recommend to systematically check the Windows Event Viewer tool for debugging and error analysis.