13.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:


General error description.


User friendly and secure message describing error.


Information about fixing problem in Web GIS context.


Corresponding HTTP 4xx or 5xx status code.


Error specific JSON-serializable dictionary.

New exception classes can be inherited from:


Base class for any other exception below and custom exceptions.


For validation errors (HTTP status code is 422).


For authorizations errors (HTTP status code is 403).


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.")

ErrorDialog can also handle dojo/request/xhr errors:

], function (
) {
    xhr(API_URL, {
        requestMethod: 'GET',
        handleAs: 'json'
        function (data) { /* everything is alright */ },