REST API

Web Exceptions - Errors

The Nuxeo API communicates error exceptions 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

KeyValue
entity-type string for exceptions is 'exception'
code string The technical exception identity (java class)
status integer The HTTP status of the error response
message string A human readable message about the error
stacktrace (extended version) string All stack trace in one simple string
exception (extended version) json object All stack trace wrapped into JSON Object

Exception Example

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

Simple Mode

JSON Response

{
  "entity-type": "exception",
  "code": "org.nuxeo.ecm.webengine.model.exceptions.WebResourceNotFoundException",
  "status": 404,
  "message": "Failed to get document /wrongID"
}

Extended Mode

{
  "entity-type": "exception",
  "code": "org.nuxeo.ecm.webengine.model.exceptions.WebResourceNotFoundException",
  "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": [
      [.................................]
}

The Automation Client requires to get the full stack trace by default. So compatibility has been kept and all automation client calls will activate the extended mode.

All calls with accepted media type application/json+nxentity will activate stack trace display.

Mode Activation API

For testing purpose, you have the possibility to activate the extended mode by adding this code snippet:

JsonFactoryManager jsonFactoryManager = Framework.getLocalService(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://localhost:8080/nuxeo/api/v1/automation/JsonStack.ToggleDisplay
    

  • use the following endpoint URL into your browser (Administrator role only).

    Type into your browser address

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

4 months ago manonlumeau Relocated assets to fit new URL structure for 710 - fix
4 years ago Solen Guitter 14 | ormat and add link about standard HTTP status code
4 years ago Solen Guitter 13 | format
5 years ago Solen Guitter 12 | Formatting and spelling
5 years ago Vladimir Pasquier 11
5 years ago Vladimir Pasquier 10
5 years ago Vladimir Pasquier 9
5 years ago Vladimir Pasquier 8
5 years ago Vladimir Pasquier 7
5 years ago Vladimir Pasquier 6
5 years ago Vladimir Pasquier 4
5 years ago Vladimir Pasquier 5
5 years ago Vladimir Pasquier 3
5 years ago Vladimir Pasquier 2 | adding web exception documentation
5 years ago Vladimir Pasquier 1
History: Created by Vladimir Pasquier

We'd love to hear your thoughts!

All fields required