Documentation
¶
Overview ¶
Package apierr is the one shape of a failure filex tells somebody about: a stable CODE a program branches on, the values its sentence takes, and the sentence itself, written by the SERVER in the reader's language.
⚠⚠ Why it exists (0.54 audit, A1/A2). The server already wrote most of its sentences in the reader's language (srvtext), but a refusal carried them in three shapes - an English sentence in `error`, a code in `error` with the sentence in `message`, an English sentence in `error` with a code beside it in `code` - and a failed queue job kept Go's own error text. The explorer threw the server's sentence away and rebuilt one from regular expressions matched against the English ("quota exceeded", "storage is read-only", "something with that name already exists here"): a Go error text that changed broke the translation silently, and the CLI and an MCP agent read "HTTP 403: permission_denied".
The envelope (docs/API-ERRORS.md):
{"error": "<code>", "message": "<sentence, reader's language>", "params": {…}}
- `error` is the code: lower-case ASCII, `[a-z0-9_]`, stable across
releases. A refusal that has always answered a code keeps it; older
clients that match on it keep working.
- `message` is `server.error.<code>` from the server catalogue (srvtext),
filled with `params`, in the reader's language (a language pack's too).
Every surface prints it as it is: the explorer, the admin panel, the
desktop app, the CLI, an MCP agent.
- `params` are the values the sentence was filled with, for a program
that wants them (a name, a limit). Optional.
A failure that is not a refusal (a queue job that failed) carries the same three things: Error is what the worker stores (Encode) instead of Go's text, and the sentence is made when the row is READ, in the language of the person reading it.
Index ¶
- func Codes() []string
- func Encode(code string, params Params, detail string) string
- func EncodeErr(err error) string
- func Key(code string) string
- func Known(code string) bool
- func Map(lang, code string, params Params, extra map[string]any) map[string]any
- func Text(lang, code string, params Params) string
- func ValidCode(code string) bool
- type Body
- type Error
- type Params
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Codes ¶
func Codes() []string
Codes is every code the catalogue has a sentence for, sorted - for the documentation test that lists them.
func Encode ¶
Encode is what a row keeps for a failure: the code, its params and the English detail when the failure has a code, else the plain text as before.
func EncodeErr ¶
EncodeErr is Encode for an error: its code when it carries one (CodeOf), its text as the detail.
func Map ¶
Map is Envelope as a map, for a refusal that carries fields of its own beside the three (a lock's `plugin`, a draft's `limit`). The three win over an extra field of the same name.
Types ¶
type Body ¶
type Body struct {
Error string `json:"error"`
Message string `json:"message"`
Params Params `json:"params,omitempty"`
}
Body is the envelope of a refusal, ready to marshal.
type Error ¶
Error is a failure with a code: what a service returns when its caller (a handler, the queue worker) must be able to say it in the reader's language later. Error() is the English detail, for logs and for an administrator's second line - never the sentence a person reads.
Source Files