18.2.3. Error handling

Backend

Any exception that needs to be reported to the user must implement interface nextgisweb.core.exception.IUserException. It can be done via subclassing exception from base exception classes from nextgisweb.core.exception module or per object basis via nextgisweb.core.exception.user_exception() method.

Exception can provide following attributes:

title

General error description.

message

User friendly and secure message describing error.

detail

Information about fixing problem in Web GIS context.

http_status_code

Corresponding HTTP 4xx or 5xx status code.

data

Error specific JSON-serializable dictionary.

New exception classes can be inherited from:

UserException

Base class for any other exception below and custom exceptions.

ValidationError

For validation errors (HTTP status code is 422).

InsufficientPermissions

For authorizations errors (HTTP status code is 403).

OperationalError

For operational errors (default HTTP status code is 503).

TODO: Add examples for user_exception().

Webserver and API

Pyramid component handles exception wich provides IUserException and processes them with following rules:

1. For API and XHR requests JSON representation returned. API requests identified by /api/ path and XHR requests identified by X-Requested-With HTTP header.

2. For other requests HTML representation returned. HTML representation is rendered by nextgisweb:pyramid/template/error.mako template.

Exceptions that doesn’t support interface IUserException wrapped into nextgisweb.pyramin.exception.InternalServerError wich support this interface, so they can be handle same way.

Titles, messages and details of exception are translated to request locate so you can use localized strings and i18n framework.

JSON representation

TODO: Add schema and example

Frontend

Сlass ngw-pyramid/ErrorDialog is designed to show modal dialog with an error message:

require(["ngw-pyramid/ErrorDialog/ErrorDialog"], function (ErrorDialog) {
    // ...
    if (somethingWentWrong) {
        new ErrorDialog({
            title: i18n.gettext("Unexpected error"),
            message: i18.gettext("Something went wrong."),
            detail: i18.gettext("Please try again later.")
        }).show()
    }
})

ErrorDialog can also handle dojo/request/xhr errors:

require([
    "dojo/request/xhr",
    "ngw-pyramid/ErrorDialog"
], function (
    xhr,
    ErrorDialog
) {
    xhr(API_URL, {
        requestMethod: 'GET',
        handleAs: 'json'
    }).then(
        function (data) { /* everything is alright */ },
        ErrorDialog.xhrError
    )
})