Errors

Edit this page

Errors are structured responses that describe failures caused by client mistakes or server problems.

TL;DR: Every error includes an HTTP status code, an error code string, a human-readable message, and an optional description with resolution hints. Use the status code for programmatic handling – the error code string may change without notice.

Overview

When a Ditto operation fails, Ditto returns an error response containing details about what went wrong and how you might fix it.

Error model

Status

The status field uses HTTP status code semantics (see RFC 7231) to indicate whether a command succeeded or failed.

The status code is part of Ditto’s stable API. Use it to identify and handle errors programmatically.

Error code

The error field contains a string identifier that uniquely identifies the error type (e.g., things:attribute.notfound).

These error codes are not part of the stable API and may change without notice. Do not rely on them for programmatic error handling.

Ditto uses these prefixes for its error codes:

Prefix	Domain
`things:`	Things
`policies:`	Policies
`things-search:`	Things search
`acknowledgement:`	Acknowledgements
`messages:`	Messages
`placeholder:`	Placeholders
`jwt:`	JWT-based authentication
`gateway:`	Gateway service
`connectivity:`	Connectivity service

Message

The message field contains a short, human-readable description of the problem.

Description

The optional description field provides more detail on how to resolve the error.

Href

The optional href field links to Ditto documentation or external resources that help resolve the error.

Examples

A “not found” error:

{
  "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."
}

An “invalid ID” error:

{
  "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"
}