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: { "message": A user friendly and (generally) localized 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. For example the ID may help your code to decide how to react to errors. See Error IDs for a complete list. "info": Optional additional description for the eyes of the developer. This should never be shown to the end user. failed": Always set to "true". } Â What error do I show to the end user? You can safely display the "message" content to the end user. It will be localized in the language you specified when connecting. Â How to I adapt the control flow of my software? The "id" value may give you an indication of what failed and may be used to decide what to do in your program. See: Error IDs. Use when you feel you need it. Â |
Other codes | FAILED Other error codes may or may not return a JSON object. These are low level errors likely due to network problems or programming errors. Problems originating inside the Wordbee API will return a JSON (see example further down). Requests failing prior to reaching the API will not return a JSON. If there is a JSON it is for your information only and must never be shown to the end user (or only as a supplement). Â What error do I show to the end user? You need to show your own generic error message such as "Oups, this operation failed". You may want to use the HTTP status code to decide what to display, for example:
For a full list of error codes see: HTTP status codes (Wikipedia) Â |
Â
EXAMPLES
Status 400 error
This is the JSON result if you had specified an invalid domain value during connection. The HTTP status code is 400.
{ "id":"LOGIN_FAILED", "message":"Login failed.", "info": "Invalid API domain: InstaTra." "failed":true }
Â
Low level error - Not network related
If you call wrong API methods or with wrongly named or missing parameters, then you get a status code 404 and a result which is formatted differently from what is described further up:
{ "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.
Â
Low level error - Network related
Returns an HTTP status code but typically does not include any other details. For example, a firewall will not describe the exact issue at hand.
If the error is generated by a proxy server then additional technical information may be returned.
Â
Â
Copyright Wordbee - Buzzin' Outside the Box since 2008