When a command fails, Ditto returns an error response containing details about what went wrong.
Overview
Ditto Protocol error responses transport information about errors caused by client mistakes or server problems.
Error response format
Each error response contains:
- status: An HTTP status code (e.g.,
400,404,500) - error: A string error code (e.g.,
things:thing.notfound) - message: A short description of the problem
- description: An optional hint on how to resolve the error
How it works
When Ditto cannot process a command, it returns an error response instead of a success response. You correlate the error with the original command using the correlation-id header.
The error response topic differs from the command topic. For example, a failed modify command may return an error with a topic ending in errors rather than commands/modify.
Error codes
The error string codes that Ditto provides (e.g., things:thing.tooLarge) are not part of the stable API. They may change without prior notice. Use the HTTP status code to identify and handle errors programmatically.
Examples
Further reading
- Errors – the error model and common error codes
- Protocol specification – the full message format reference