Outcomes and errors

The error envelope

REST answers a failure with an HTTP error status and this body:

{
  "error": {
    "code": "THING_UNAVAILABLE",
    "message": "THING_UNAVAILABLE",
    "correlationId": "req_...",
    "outcome": "not-executed"
  }
}

Field	Meaning
code	The error code, from the table below
message	Currently the same as code
correlationId	An ID for this request, to quote when reporting a problem
outcome	Present when Nodelets can say whether the device acted

MCP tools return the same object as their structured content, with isError: true. The bridge stream puts code and outcome in the error’s data. See MCP tools and WebSocket.

Outcomes

Outcome	Meaning	What to do
not-executed	The device did not act. Nothing reached it, it refused with an HTTP error, or a read ran out of time	It is safe to try again
unknown	A write or action may have reached the device, but nothing confirmed it	Check the device’s state before trying again. A repeat is a new command
absent	The request failed before an operation was attempted, or it was a read	Read the code

Nodelets sends each operation once and never resends it, and it never reports success it cannot back. A successful write or action means the device accepted it: for HTTP, a 2xx status; for MQTT, a matching confirmation message.

Codes

Code	Status	Outcome	Cause
INVALID_INPUT	400	not-executed when checked against a definition	The request was malformed, too large, not JSON, or its value does not match the definition’s schema
UNAUTHENTICATED	401		No key, or a key that is not valid or has been deleted
PERMISSION_DENIED	403	not-executed	The credential reaches the Nodelet but is not given this capability or operation
NOT_FOUND	404		No such Nodelet, or one the credential does not reach, or one that was removed
UNSUPPORTED_OPERATION	400	not-executed	The definition has no binding for this operation, for example a write to a read-only property
CONFIG_PENDING	409		The Thing’s latest change, or its removal, has not been acknowledged yet
BRIDGE_UNAVAILABLE	503	not-executed when nothing was sent	The bridge is not connected, or its connection dropped during a read
THING_UNAVAILABLE	503	not-executed	The bridge could not reach the device or the MQTT broker
BUSY	503	not-executed	The bridge already has 64 commands in flight
DEVICE_ERROR	502	not-executed	The device answered with an HTTP status outside 200 to 299
INVALID_DEVICE_VALUE	502	not-executed for a read, unknown for an action	The device’s reply was not JSON, lacked the value at the pointer, did not match the schema, or exceeded 256 KiB
TIMEOUT	504	not-executed, or absent	A read, or the setting up of a subscription, ran out of time
OUTCOME_UNKNOWN	504	unknown	A write or action ran out of time, or its connection dropped, after it was sent
CANCELLED	400	not-executed	A read was cancelled before it finished
INTERNAL_ERROR	500		A fault inside Nodelets

Codes from the CLI

The CLI explains these in plain words, with what to do next.

Code	Meaning
BRIDGE_OFFLINE	The bridge is not connected, so Things cannot be added, changed or removed
DEFINITION_CONFLICT	A different definition with this ID is already installed
DEFINITION_NOT_FOUND	No definition with that ID is installed
DRIVER_NOT_FOUND	The definition uses a driver this bridge does not include
NOT_ENROLLED	The bridge has no identity to recover. Register it instead
REMOVED_IN_CLOUD	The Thing was removed from Nodelets and cannot return

nodelets thing show ID lists the last error a Thing met, with its code and how long ago.