autotel-structured-errors

Files (1)

• SKILL.md

SKILL.md (first lines)

# Autotel: Structured Errors

Throw errors with `createStructuredError({ message, why?, fix?, link?, status?, cause? })` in API routes and services. On the client, use `parseError(caught)` to get `message`, `status`, `why`, `fix`, `link` for toasts and UI.

## Setup

**Server (API route or service):**

```typescript
import { createStructuredError } from 'autotel';

if (!user) {
  throw createStructuredError({
    message: 'User not found',
    status: 404,
    why: `No user with ID "${userId}"`,
    fix: 'Check the user ID and try again',
    link: 'https://docs.example.com/errors/user-not-found',
  });
}
```

**Client:**

```typescript
import { parseError } from 'autotel';

try {
  await fetch('/api/checkout', { method: 'POST', body: JSON.stringify(data) });
} catch (err) {
  const e = parseError(err);
  toast.error(e.message, { description: e.why });
  if (e.fix) setHelp(e.fix);
  if (e.link) setDocLink(e.link);
}
```

## Core Patterns

**Wrap a caught error (preserve cause):**

```typescript
try {
  await stripe.charges.create(data);
} catch (err) {
  throw createStructuredError({
    message: 'Payment failed',
    status: 402,
    why: err instanceof Error ? err.message : 'Unknown error',
    fix: 'Try a different payment method or contact support',
    link: 'https://docs.stripe.com/declines',
    cause: err,
  });
}
```

**Same error from several places:** define it once with `defineErrorCatalog` instead of copying the wording.

```typescript
import { defineErrorCatalog } from 'autotel';

export const billing = defineErrorCatalog('billing', {
  PAYMENT_DECLINED: {
    status: 402,
    message: 'Card declined',
    why: 'The issuer rejected the charge',
    fix: 'Try a different payment method',
  },
  INSUFFICIENT_FUNDS: {
    status: 402,
    message: ({
      available,
      required,
    }: {
      available: number;
      required: number;
    }) => `Insufficient funds: $${available} of $${required}`,
  },
});

throw billing.PAYMENT_DECLINED({ cause: stripeError });
throw billing.INSUFFICIENT_FUNDS({ available: 5, required: 100 });

if (billing.PAYMENT_DECLINED.match(err)) retryWithDifferentCard();
```

Builders return the same `StructuredError`, so `parseError()` still works. Codes default to `namespace.KEY`. A function `message` or `why` takes typed params enforced at every call site. `.match()` compares the catalog code, so renaming an entry breaks the compile instead of skipping the branch.

**Record on current span:** `createStructuredError()` only builds the error; it touches no span. Thrown out of a `trace()` body, it sets the span's ERROR status and records the exception. The structured fields (`error.why`, `error.fix`, `error.link`, `error.code`, `error.status`) reach the span only through `recordStructuredError(ctx, error)` or the request logger's `.error(error, fields)`:

```typescript
import { recordStructuredError } from 'autotel';

catch (err) {
  const e = billing.PAYMENT_DECLINED({ cause: err });
  recordStructuredError(ctx, e); // or getRequestLogger().error(e)
  throw e;
}
```

For new exception event flows, prefer request-logger/log-based correlation and keep span-event compatibility as an implementation detail (processors/export path), not a new app-level dependency.

**parseError** handles FetchError (ofetch), nested `data.data`, and plain Error. Returns `{ message, status, why?, fix?, link?, raw }`.

## Common Mistakes

### HIGH Throw new Error() in API routes instead of createStructuredError

Wrong:

```typescript
throw new Error('Payment failed');
```

Correct:

```typescript
throw createStructuredError({
  message: 'Payment failed',

From jagreehal/autotel, Apache-2.0.

More from jagreehal/autotel