# Sort one boundary's errors into named categories

Errors thrown with no type, replaced by named categories that each say what to do about them.

Category: Observability and operability
Source: https://letsship.ai/use-cases/give-one-boundary-a-typed-error-taxonomy
Published: 2026-08-25

## Goal

Replace untyped errors at one boundary with a typed taxonomy carrying causes and remedies.

## Acceptance criteria

- Each error category is a distinct type with a cause and a remedy
- Callers can branch on category without matching on message strings
- Each category has a test
- Unclassified failures surface as an explicit unknown rather than being swallowed

## What lands as proof

A test per category asserting the classification, so error handling stops depending on message text.

## Prompt

Copy this to an agent to open the ticket:

```text
Create a Linear issue in my team and assign it to the SHIP agent.

Title: Add a typed error taxonomy to {boundary}

Description: Replace untyped errors at one boundary with a typed taxonomy carrying causes and remedies.

Acceptance criteria:
- Each error category is a distinct type with a cause and a remedy
- Callers can branch on category without matching on message strings
- Each category has a test
- Unclassified failures surface as an explicit unknown rather than being swallowed

Before you create the issue, find a boundary in this repository that throws untyped errors and replace {boundary} with it.
```

## Questions

### What does the agent actually change?

The ticket is scoped to one outcome: replace untyped errors at one boundary with a typed taxonomy carrying causes and remedies. Work that serves that outcome is in scope, and anything outside it is left for a separate ticket, so the pull request stays reviewable.

### How do I know the work is done?

The pull request carries the evidence, not only the diff. Here that means each category carries a test and a stated remedy, so a reviewer can confirm the result without reproducing the work locally.

### How much oversight does this need?

The run stops once the plan is written. Somebody reads the approach and approves it before any code exists, which is the cheapest moment to redirect the work.