Structured Error Handling

Structured errors carry a stable code and descriptive message rather than requiring callers to match human text. Keep expected domain errors distinct from unexpected runtime failures. HTTP adapters can translate codes to statuses while application logic handles failures as values or typed exceptions.

The discriminant ok narrows each union branch. Callers can map EMPTY to a 400-style response without string-parsing an exception message.

Not every thrown error is an expected validation failure. Unknown exceptions need logging and a safe public response.

This source was compiled using TypeScript 5.8.3 with strict checking, then executed with Node.js 22.16.0. Its stdout below is the actual captured output. The core logic is runnable without a framework or a remote API; integration-specific examples appear in a separate lab when needed.

TypeScript source

type Result<T> = { ok: true; value: T } | { ok: false; code: "EMPTY" | "TOO_LONG" };
function normalizeTitle(raw: string): Result<string> {
  const title = raw.trim();
  if (!title) return { ok: false, code: "EMPTY" };
  if (title.length > 20) return { ok: false, code: "TOO_LONG" };
  return { ok: true, value: title };
}
for (const input of ["  Read  ", "  "]) {
  const result = normalizeTitle(input);
  console.log(result.ok ? result.value : `Error: ${result.code}`);
}

Verified output

Read
Error: EMPTY

Compile: npx tsc --strict --target es2022 --module commonjs structured-error-handling.ts; run: node structured-error-handling.js. For examples importing node: modules, install @types/node as a development dependency; for browser or React projects use the separate lab setup.

The discriminant ok narrows each union branch. Callers can map EMPTY to a 400-style response without string-parsing an exception message.

Before editing the code, predict what the output will be for one changed input. Run it and compare your prediction with the actual result.

Not every thrown error is an expected validation failure. Unknown exceptions need logging and a safe public response.

Determine whether the issue belongs to the type system, a trust boundary, or actual runtime behavior before choosing a correction.

Map EMPTY and TOO_LONG to separate user-facing messages. Add a test that checks the error code, not the wording.

Record expected success and failure outcomes, run the code, and compare the observed behavior. Keep the exercise compatible with strict type checking.

The discriminant ok narrows each union branch. Callers can map EMPTY to a 400-style response without string-parsing an exception message.

Apply the same reasoning to the practice task, then integrate it into a real app only when the runtime and dependency setup are ready.