# ADR-0113: A small, stable error-code taxonomy

- **Status:** Accepted
- **Date:** 2026-06-26
- **Deciders:** jka
- **Decision:** no D number

## Context

ADR-0011's first responses carried `error` as a bare string. Clients could display it but
not act on it, and an uncaught Tcl error risked reaching a client as a stack trace. The GUI
also read `result` without checking `ok`, and crashed on a failed operation.

## Decision

An error reply's `error` is an object `{code, message}`: a stable, machine-readable code
that clients branch on, and a human message for display.

The vocabulary is deliberately small:

| Code | Meaning |
| ---- | ------- |
| `bad_request` | The request is invalid, or the operation refused it (including git's own refusals). |
| `unknown_op` | No such operation. |
| `no_buffer` | The buffer id does not exist. |
| `no_path` | A save needs a path and the buffer has none. |
| `bad_index` | A `line.col` index is out of range or malformed. |
| `io_error` | A filesystem, launch or network failure. |
| `untrusted_cert` | The core refused a TLS certificate; the client may offer a review (ADR-0111). |
| `internal` | Any uncaught error, so a defect still produces a clean reply. |

An operation raises `rio::error::raise <code> <message>`, which carries the code in Tcl's
`-errorcode`; dispatch shapes the reply. Changing `error` from a string to an object bumped
the protocol version to 2.

## Consequences

- The GUI checks `ok` before reading `result` and reports failures through one
  `report_error` path.
- A new code is added only when a client needs to act differently;
  `untrusted_cert` (2026-09-15) is the only addition so far.
- A test holds the vocabulary, so a new code cannot be added silently.