Server

Error Handling

Updated: September 14, 2020

The Nuxeo API communicates error messages through standard HTTP status codes paired with exception details.

You can find more details about standard HTTP status codes on:

Two modes are available:

  • Simple (without exception stack trace)

  • Extended (with exception stack trace)

Simple mode is activated by default. The extended mode can be configured through a parameter (in nuxeo.conf): org.nuxeo.rest.stack.enable=true.

Properties

Key Type Value
entity-type string 'exception' (in the case of exceptions)
status integer The HTTP status of the error response
message string A human-readable message about the error
stacktrace string The entire stack trace in one string
exception JSON object The entire stack trace wrapped into a JSON Object

Exception Example

Here is an example of an exception when fetching a missing document.

Simple Mode

JSON Response

{ "entity-type": "exception", "status": 404, "message": "Failed to get document /wrongID" }

Extended Mode

{ "entity-type": "exception", "status": 404, "message": "Failed to get document /wrongID", "stacktrace": "org.nuxeo.ecm.webengine.WebException: Failed to get document /wrongID\n\tat org.nuxeo.ecm.webengine.WebException.newException(WebException.java[.........]", "exception": { "className": "org.nuxeo.ecm.webengine.model.exceptions.WebResourceNotFoundException", "cause": { "className": "org.nuxeo.ecm.core.model.NoSuchDocumentException", "cause": null, "message": "No such document: No such document: /wrongID", "localizedMessage": "No such document: No such document: /wrongID", "stackTrace": [ [.................................] ] } } }

Mode Activation API

For testing purposes, you can activate the extended mode by adding this code snippet:

JsonFactoryManager jsonFactoryManager = Framework.getService(JsonFactoryManager.class); if (!jsonFactoryManager.isStackDisplay()) { jsonFactoryManager.toggleStackDisplay(); }

To toggle the display mode (simple or extended) during runtime execution, you can:

  • Use the Automation JsonStack.ToggleDisplay Operation (Administrator role only) Example:

    cURL Call

    curl -H 'Content-Type:application/json+nxrequest' -X POST -d '{"params":{},"context":{}}' -u Administrator:Administrator http://NUXEO_SERVER:8080/nuxeo/api/v1/automation/JsonStack.ToggleDisplay

  • Use the following endpoint URL in your browser (Administrator role only)

    Type into your browser address

    http://NUXEO_SERVER/nuxeo/site/automation/doc/toggleStackDisplay

Custom HTTP Status Code

Since Nuxeo Platform 9.3, you can customize the HTTP status code returned by the Nuxeo Platform when throwing a NuxeoException.

Default subclasses of NuxeoException are already mapped to the right HTTP status code, such as:

  • DocumentNotFoundException: 404
  • DocumentSecurityException: 403
  • ConcurrentUpdateException: 409
  • WebResourceNotFoundException: 404
  • ...

The NuxeoException class supports new constructors where you can specify a status code that will be used as the response HTTP status code. The mapping of the NuxeoException#statusCode with the response HTTP status code is done by the WebEngineExceptionMapper class.

For instance, calling a REST API endpoint where a listener throws the following exception will lead to a response with its HTTP status code set to 409.

... public void handleEvent(Event event) { ... throw new NuxeoException("there is a conflict!", 409); } ...