06-big-tree-and-apis/06-error-shapes.md

Error shapes

Error shapes

APIs and scripts should return errors in a predictable shape so callers can handle failures consistently.

Preferred pattern

Use a consistent result envelope when possible:

{ ok: true, result: ... }

When an error occurs, return:

{ ok: false, error: "message", code?: "ERROR_CODE" }

This makes it easy for callers to check ok and inspect error and optional code.

Guidelines

• Keep error messages short and actionable.
• Use optional error codes for programmatic handling.
• Avoid throwing raw, unstructured errors across network boundaries.

Client-side handling

API clients should normalize errors so UI code receives clear messages and predictable shapes.

Example:

if (!res.ok) {
  throw new Error(res.error || "Request failed");
}

Final rule

Keep error shapes stable and predictable so debugging and automated handling remain simple.