Errors (C++)

The C++ SDK keeps three error types separate. HostError means the application could not start or shut down. ActionError is what a handler returns when an invocation fails. ProtocolError is the JSON-RPC error object that crosses the connection.

TesseronErrorCode is the closed set of protocol codes. to_wire_code(...) returns the JSON-RPC integer, and from_wire_code(...) returns std::nullopt for an integer this SDK does not define.

Handlers return boost::asio::awaitable<Result<Json>>. Startup returns Result<Host, HostError>, and shutdown returns Result<void, HostError>. A handler can return a domain failure through ActionError::handler(message), a chosen code through ActionError::protocol(code, message, data), or a local cause through ActionError::internal(source).

The todo example's helper returns -32005 HandlerError with data when an id is unknown:

ActionError todo_not_found() {
  return ActionError::protocol(tesseron::TesseronErrorCode::HandlerError, "Todo not found",
                               Json{{"kind", "not_found"}});
}

The toggleTodo and deleteTodo handlers co_return todo_not_found() when their lookup reaches the end. Use ActionError::handler(message) for the same -32005 code without custom data. Use ActionError::protocol(code, message, data) when the agent needs a specific code and structured detail. Use ActionError::internal(source) when the failure is a bug rather than a domain outcome. Its cause stays local and the agent receives -32603 Internal error. A handler that throws is treated the same way.

ProtocolError represents the JSON-RPC error member with an integer code, a message, and optional JSON data. The integer stays available even when it is outside TesseronErrorCode, so a newer gateway's code can round-trip. named_code() returns std::nullopt for that unknown integer.

Construct it with either a TesseronErrorCode or a raw integer. with_data(...) attaches structured detail, to_json() makes the wire payload, and from_json(...) reads one when the shape is valid.

The host follows the wire-format rules for request IDs. An id: null member still marks a request, and its response carries id: null. Only an absent id makes a notification, so a notification receives no response.

A frame without jsonrpc: "2.0" receives -32600 InvalidRequest. The host carries through a usable string, number, or null id, and uses null when there is no usable id. The session stays up after this response and can process the next frame.

These errors happen before an invocation reaches a handler:

listen() refuses a non-loopback address before binding. shutdown() reports manifest removal failures through Result<void, HostError>.