Server

Error Handling

Updated: March 18, 2024

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);
    }
...