Error Handling

Introduction

In case of an error, a service does not return the json normally expected for the service. It is already advisable to always test the HTTP code and bifurcate to error handling when the code is not a 2xx. Then, the JSON returned contains the following properties:

error: unique error code
subcode: optionnaly, more accurate error code
message: plain text message
submessage: optionally, more accurate error message
errorSupportDetails: error details to allow automatic forwarding to a support email
error_uri: uri of the error documentation (if any)
errorWithContact: boolean, true if the error message contains a statement such as "please contact your administrator". You can use this information to decide whether or not to display the contact indication of the support, for example
errtag: a tag to retrieve the corresponding trace in server logs
cause: stacktrace of error, only in debug mode
time: 2024.4 UTC date-time of the error (this date-time is as close as possible to the actual date-time on which the exception is thrown, but there may be a slight delay (Java exceptions are not basically dated). The main aim is to be able to retrieve the event log where the trace of the exception can be found)

It is therefore also possible to test whether the response contains the attribut error before further discovery of the response. In addition, in debug mode, we can consult the cause attribute that gives the stacktrace of the exception if necessary. Debug mode is enabled by default in development mode, and deactivated in production mode. The debug query parameter controls this mode.

The error code, unique for the whole API, is always composed of two parts separated by a slash: first the http code, second a specific code. This code can be used to react specifically to the error in a dedicated code. The codes are listed in the sections of each endpoint of this documentation.

The message is an unencrypted, localised message, usually intended to be displayed to a user. It can be associated with a mention of the style "Please warn your administrator" on some error codes (view unknown for example). Logging the error, along with the query, is extremely useful to handle the problem downstream. In any case, the error will be logged in the plugin’s specific log, with its stacktrace, debug mode, or not.

For some error cases, this structure will be missing: it is necessary to provide a fallback for all 4xx and 5xx codes to display a generic message.

error details

Error details allows to show a message to help user to send an email to support. The property may be missing to not display this information.

structure

value: a message indicating the email address to report the errora message indicating the email address to report the error (can be null or absent)
key: a key allowing the client to generate his own message from his own resource bundle
params: the parameters for the client generated message (default is the Wedia support email)

customization

It is possible to customize this message by configuring the plugin, or disable it, with the property errorSupport as a JSon structure:

[
    {
        "key": "WEDIA_ERROR_SUPPORT",
        "params": [
            "support@wedia-group.com"
        ]
    }
]

value: a static message

key: the error message key
params: the error message parameter list. You can change here the email to support, to provide a company first level email address (first parameter).

if you customize the message so that the plugin is no longer able to evaluate a message corresponding to the key, use the value parameter to set a static default message that will allow a client who is not using the key to display a standard message, or null to not display any message.

available keys

The plugin provides two messages by default, here are the keys:

WEDIA_ERROR_SUPPORT: standard message with email to support
EMAIL_ERROR_SUPPORT: the same message as the standard message but without the mention "Wedia"

Error documentation URL

The remote URI to get the documentation of errors is https://<host>/api/rest/errors. You can add an anchor to a specific message with the error code: https://<host>/api/rest/errors#404/601.

This documentation only shows messages for end users, without the details that could be obtained in debug mode. It specifies the conditions for obtaining the error, in particular to enable an intermediary to know where to escalate the error if necessary, and some other informations to qualify the error.

This documentation is also accessible from the document portal via the url this documentation is also accessible from the document portal via the url https://<host>/api/rest/docportal/errors.

Available informations in the documentation

1	The WEDIA error code followed by the error message (as it appears to the end user in production mode (without contextual/debug details))
2	The main types of errors, giving information on the type of problem (an invalid parameter value, a configuration problem, a security problem...).
3	The HTTP code (status) of the error
4	The circumstances or conditions under which the error occurs, or the causes of the error. On the right, icons indicate when : the message displayed in production is different from the one displayed in development/debug mode (the messages displayed in production are generally vague, while those displayed in debug mode are contextualized to facilitate debugging); the main message is supplemented by a more precise secondary message on the circumstances of the error (in this case, it is described in additional information in the documentation, between 5 and 6); the message contains an invitation to contact an administrator (this is an error that cannot be corrected by the API consumer, and requires either the intervention of an administrator or the intervention of Project Services); the error has an error sub-code specifying more precisely the type of error.
5	Optionally, more precise explanations on the circumstances or conditions with possibly indications on how to solve it (for example, if the problem comes from security, or from a configuration, or if it is up to the consumer to provide a missing parameter, etc). This information only appears to users connected as administrators or as BO user with rights to access the document portal.
6	The log level needed to see this error in the logs