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: 404: This clearly is your error, you are calling an nonexistent API method. 408: The request timed out. This may point to a very slow Internet connection or a non-responsive Wordbee Translator platform. Typically, you would ask the user to retry. 500 and higher: This is an error inside Wordbee Translator and may be a bug or non-intercepted error case. You can only show a generic failure message. 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.