Nuxeo Server

Error Handling

Updated: January 18, 2018 Page Information Edit on GitHub

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);
    }
...
12 hours ago manonlumeau Review LTS 2017
16 days ago manonlumeau NXP-23872: deprecate Framework.getLocalService
a month ago Manon Lumeau add tags for doc days
2 months ago Manon Lumeau Update tag on rest-api component
2 months ago manonlumeau NXDOC-1360: custom HTTP status code when throwing an exception
2 months ago manonlumeau Added content-review-lts2017 label
3 months ago manonlumeau NXDOC-1346-FT review screenshot
3 years ago Solen Guitter 14
3 years ago Solen Guitter 13 | format
3 years ago Solen Guitter 12 | Formatting and spelling
3 years ago Vladimir Pasquier 11
3 years ago Vladimir Pasquier 10
3 years ago Vladimir Pasquier 9
3 years ago Vladimir Pasquier 8
3 years ago Vladimir Pasquier 7
3 years ago Vladimir Pasquier 6
3 years ago Vladimir Pasquier 4
3 years ago Vladimir Pasquier 5
3 years ago Vladimir Pasquier 3
3 years ago Vladimir Pasquier 2 | adding web exception documentation
3 years ago Vladimir Pasquier 1
History: Created by Vladimir Pasquier