# Errors are part of the interface

> For agents: start with the [agent guide](https://ratstack.sh/llms.txt). Every page is Markdown by default; add `Accept: text/html` for HTML.

New on /news: [Foldkit 0.171.0 requires result Message schemas](/news).

The [code-snippets design brief](/lore/code-snippets) requires an author-facing error for each rejected snippet.

Each error carries:

- A typed error tag: the name identifying the declared error type.
- The source document and line.
- The rejected request.
- Requested ranges and actual file length, when available.
- A repair instruction.

The `CodeRangeOutOfBounds` error class also has a brand.
The brand stops two classes with the same fields from being assignable to each other.

Invalid metadata keeps its raw values. It has no decoded request yet.

The author needs the rejected input, its location, and a repair instruction. A stack trace alone cannot supply them.

Use the [error model](/lore/error-model) to separate expected failures from defects.
Use [schema decoding](/lore/schemas-define-the-boundary) to reject invalid input at the boundary.
The [error accumulation example](/lore/accumulate-independent-errors#worked-example-collect-snippet-failures) shows how the snippet pipeline collects unrelated failures into one build error.

Related reading: *Exceptional Ruby* and *Confident Ruby*, both by [Avdi Grimm](https://avdi.codes/books/).

See the glossary for [diagnostic context](/glossary) and repair instruction.

## Sources

1. [Avdi Grimm's books](https://avdi.codes/books/)
   Avdi Grimm. Author and titles only; no claims about book contents. Accessed 2026-10-02.

2. [Effect Schema](https://github.com/Effect-TS/effect/blob/effect%404.0.0/packages/effect/src/Schema.ts)
   Effect contributors. Typed errors Accessed 2026-10-02.

3. [Code-snippets design brief](https://github.com/joelhooks/rat-stack/blob/main/.brain/resources/lore/code-snippets.svx)
   Primary source. Proposed diagnostic contract Accessed 2026-10-02.

## Linked from

- Accumulate independent errors before writing output → Check every independent job before any job writes an asset. → [Read page](https://ratstack.sh/lore/accumulate-independent-errors)

- Agent guide → An Effect stack so pure (aspirational) Kit Langton will blush. → [Read page](https://ratstack.sh/llms.txt)

- Change log → What changed in the files served here, newest first. → [Read page](https://ratstack.sh/log)

- Code snippets quote a pinned source → Shipped design brief: pinned Git objects, typed diagnostics, and one build-only snippet model for both views. → [Read page](https://ratstack.sh/lore/code-snippets)

- Flags climb on evidence → A flag ladder connects each rollout step to scoped measurements, approval, and a durable receipt. → [Read page](https://ratstack.sh/lore/flags-climb-on-evidence)

- Full agent guide → An Effect stack so pure (aspirational) Kit Langton will blush. → [Read page](https://ratstack.sh/llms-full.txt)

- Handle expected failures without hiding defects → Declare expected failures, preserve their context, and recover by tag without turning crashes into successful outcomes. → [Read page](https://ratstack.sh/lore/error-model)

- Rat Stack lore | rat-stack → Short, source-grounded notes on the ideas and decisions behind rat-stack. → [Read page](https://ratstack.sh/lore)

- Source change history (log.md) → The generated change log as Markdown. → [Read page](https://ratstack.sh/log.md)
