Error Handling Patterns skill for Codex

Error handling is right when every failure is either handled meaningfully or propagated with context, each error is logged once with enough detail to debug, users see a safe and actionable message, callers can tell expected failures apart by type rather than by parsing strings, and nothing is silently swallowed.

Before changing anything

• Read AGENTS.md and sample existing error code: rg -n "class \w+(Error|Exception)\b|errors\.New|fmt\.Errorf|new Error\(|catch \(|except " | head -50.
• Find the boundaries where errors leave the system: HTTP handlers or middleware, CLI main, job runners, message consumers. Most fixes belong there.
• Note the project’s choice of exceptions vs result types and follow it; do not introduce a Result library into an exception-based codebase on your own.

Classify failures first

Class	Examples	Handling
Expected domain outcome	not found, validation failed, insufficient funds, conflict	Typed error or result value; mapped to a 4xx or a user message; logged at info or not at all
Transient infrastructure	timeout, connection reset, 503, deadlock, rate limit	Retry with backoff and jitter where the operation is idempotent; otherwise surface
Permanent infrastructure	auth to a dependency failed, missing config, schema mismatch	Fail fast and loudly; alert; do not retry
Programmer error (bug)	null dereference, broken invariant, unreachable branch	Let it crash the request or task; 500; log with stack; fix the code

Do not catch bugs in order to “handle” them. Catching Exception or error around business logic turns bugs into wrong results.

A small error taxonomy

Define a handful of domain error types in one module, each with a stable machine code. Callers branch on type or code, never on message text.

# errors.py
class AppError(Exception):
    """Base for expected, classified failures. Message is internal; public_message is safe."""
    code = "internal"
    status = 500
    public_message = "Something went wrong."

class NotFound(AppError):
    code, status, public_message = "not_found", 404, "The resource was not found."

class ValidationFailed(AppError):
    code, status = "validation_failed", 422
    def __init__(self, message: str, fields: dict[str, str]):
        super().__init__(message)
        self.fields = fields
        self.public_message = "Some fields are invalid."

class Conflict(AppError):
    code, status, public_message = "conflict", 409, "The resource was changed by someone else."

// errors.ts
export class AppError extends Error {
  constructor(
    message: string,
    readonly code: string,
    readonly status = 500,
    options?: { cause?: unknown },
  ) {
    super(message, options);   // ES2022 Error cause
    this.name = new.target.name;
  }
}
export class NotFoundError extends AppError {
  constructor(what: string, options?: { cause?: unknown }) {
    super(`${what} not found`, "not_found", 404, options);
  }
}

// errors.go
var ErrNotFound = errors.New("not found")        // sentinel for errors.Is

type ValidationError struct{ Fields map[string]string }
func (e *ValidationError) Error() string { return fmt.Sprintf("validation failed: %v", e.Fields) }

For Rust, use thiserror for library error enums and anyhow at application edges (see rust-error-handling for detail).

Propagate with context, keep the cause

Wrap when crossing a layer, adding what the lower layer did not know (which order, which file). Never drop the original error.

try:
    row = repo.load(order_id)
except psycopg.OperationalError as e:
    raise StorageUnavailable(f"loading order {order_id}") from e    # keeps __cause__

try {
  await repo.load(orderId);
} catch (err) {
  throw new AppError(`loading order ${orderId}`, "storage_unavailable", 503, { cause: err });
}

row, err := repo.Load(ctx, orderID)
if err != nil {
    return fmt.Errorf("loading order %s: %w", orderID, err)    // %w keeps the chain
}
// callers:
if errors.Is(err, ErrNotFound) { ... }
var ve *ValidationError
if errors.As(err, &ve) { ... }

Rules:

• Use %w (Go), from e (Python), { cause } (JS) every time you wrap. %v or string concatenation breaks errors.Is and loses the stack.
• Do not wrap at every function; wrap at meaningful boundaries (repository, service, client).
• Combine independent failures with errors.Join (Go 1.20+), ExceptionGroup (Python 3.11+) or AggregateError (JS) instead of keeping only the first.

Handle once, at the boundary

Log and translate errors in one place per entry point. Intermediate layers either handle the error completely or propagate it; they do not log and rethrow.

@app.exception_handler(AppError)            # FastAPI example
async def app_error_handler(request, exc: AppError):
    if exc.status >= 500:
        log.error("request failed", exc_info=exc, extra={"code": exc.code, "path": request.url.path})
    return JSONResponse(
        status_code=exc.status,
        content={"type": exc.code, "title": exc.public_message,
                 "request_id": request.state.request_id},
    )

Unknown exceptions reach a catch-all that logs with stack trace and returns a generic 500 with a request ID. For RFC 9457 problem details response bodies, see problem-details-errors.

User-facing vs internal

Internal message (logs)	Public message (response, UI)
loading order 8812: connection refused to db-primary:5432	“We could not load your order. Try again in a minute. (ref 7f3a)”
Stack trace, SQL, file paths, upstream response bodies	Never
Validation detail with field names	Field-level messages the user can fix

Never put secrets, tokens, personal data or raw SQL into error messages; they end up in logs, alerts and sometimes responses. Wording of user-facing messages is covered by error-messages.

Retries

Retry only transient errors, only idempotent operations (or with idempotency keys), with exponential backoff, jitter, a cap on attempts and an overall deadline. Retrying at several layers multiplies attempts (3 x 3 x 3 = 27 calls). Pick one layer. Circuit breakers and bulkheads are in resilience-patterns.

Anti-patterns to remove

rg -n "except\s*:|except Exception\s*:\s*$" --type py -A2 | rg -n "pass|continue"   # swallowed
rg -n "catch\s*\(\w*\)\s*\{\s*\}" --type ts                                             # empty catch
rg -n "_ = err|_ = \w+\.Close\(\)" --type go                                             # ignored errors

• Empty catch blocks or except: pass.
• catch (e) { console.log(e) } and continue as if nothing happened.
• Returning null, -1 or "" for failures callers cannot distinguish from data.
• Log-and-rethrow at every layer (the same error appears five times in logs).
• Branching on err.message.includes("not found").
• finally blocks that throw and mask the original error.
• Converting every error to 500, or every error to 400.

Workflow

- [ ] 1. Inventory boundaries and current error types
- [ ] 2. Classify failures the code can produce (table above)
- [ ] 3. Introduce or consolidate the taxonomy (few types, stable codes)
- [ ] 4. Add wrapping with cause at layer boundaries
- [ ] 5. Centralise logging and mapping at each boundary
- [ ] 6. Remove swallowed errors and duplicate logging
- [ ] 7. Test each error path (below)

Verification

• Tests assert on error type or code, not message text, for each expected failure: pytest.raises(NotFound), await expect(p).rejects.toBeInstanceOf(NotFoundError), errors.Is(err, ErrNotFound).
• A forced dependency failure (stopped database, mocked timeout) produces one log line with the full cause chain and a safe response with a request ID.
• The anti-pattern searches above return nothing new in changed files.

Output

**Taxonomy:** AppError -> NotFound(404), ValidationFailed(422), Conflict(409), StorageUnavailable(503)
**Boundary:** api/middleware/errors.py maps AppError; catch-all logs stack, returns 500 + request_id
**Removed:** 7 swallowed exceptions, 12 log-and-rethrow sites
**Wrapping added:** repos/*.py (raise ... from e), clients/payments.py
**Tests:** 9 new error-path tests asserting on type/code