Edit this page

Errors are datatypes containing information about occurred failures which were either cause by the user or appeared in the server.

Error model specification

Status

The “status” uses HTTP status codes semantics (see RFC 7231) to indicate whether a specific command has been successfully completed, or not.

These “status” codes can be seen as API/contract which will be always the same for a specific error.
Use the “status” in order to identify an error, as the additional “error” and “description” might change without prior notice.

Error

A Ditto error contains an “error” code which is a string identifier that uniquely identifies the error.

These error codes Ditto provides in addition to the HTTP status code are not to be considered as API and must therefore not be relied on.
They might change without prior notice.

Ditto itself uses the following prefixes for its error codes:

Message

The error “message” contains a short message describing the encountered problem in plain english text.

Description

The optional error “description” describes in more detail how the error could be resolved.

Href

The optional href contains a link to Ditto documentation or external resources in order to help to resolve the error.

Examples

{
  "status": 404,
  "error": "things:attribute.notfound",
  "message": "The attribute with key 'unknown-key' on the thing with ID 'org.eclipse.ditto:my-thing' could not be found or the requester had insufficient permissions to access it.",
  "description": "Check if the ID of the thing and the key of your requested attribute was correct and you have sufficient permissions."
}

{
  "status": 400,
  "error": "messages:id.invalid",
  "message": "Thing ID 'foobar2000' is not valid!",
  "description": "It must conform to the namespaced entity ID notation (see Ditto documentation)",
  "href": "https://www.eclipse.dev/ditto/basic-namespaces-and-names.html#namespaced-id"
}
Tags: model