10 ERROR REPRESENTATION

The Error representation defines a standard means for returning detailed diagnostics, typically when a server-side error (status code 500) occurs.

For example, the following might be the result of invoking an action where an exception occurred:

{
  "message": "IllegalStateException",
  "stackTrace": [
    "at Somefile.java#foo():1234",
    "at SomeOtherFile.java#bar():4321"
  ],
  "causedBy": {
    "message": "IllegalStateException",
    "stackTrace": [
      "at LibraryFile.java#foz():567",
      "at LibraryOtherFile.java#baz():765"
    ]
  },
  "links": [ ... ],
  "extensions": { ... }
}

where:

JSON-Property Description

message

the exception message, typically as generated by the underlying implementation programming language.

stacktrace

(optional) list of strings representing call stack

causedBy

(optional) underlying cause of the exception (to handle nested exception scenarios).

links

list of links to other resources

extensions

additional information about the resource

"stacktrace"

The stack trace is optional. Implementations are free to suppress this information if they wish, or to make available only if a debug flag (or similar) has been enabled.

Restful Objects defines no standard links/json-properties for "links" and "extensions", but implementations are free to add to their own links/json-properties as they require.