Error Handling

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