TypeScript Error Handling

The SDK throws typed errors for API failures, validation issues, and network problems. The taxonomy mirrors the API’s ErrorResponse envelope, with subclasses per HTTP class for ergonomic catching.

Error class hierarchy

DevhelmError                  ← umbrella; catch as a fallback
├── DevhelmValidationError    ← local request/response shape validation
├── DevhelmTransportError     ← connection refused, DNS, TLS, timeout
└── DevhelmApiError           ← non-2xx HTTP response
    ├── DevhelmAuthError      ← 401, 403
    ├── DevhelmNotFoundError  ← 404
    ├── DevhelmConflictError  ← 409
    ├── DevhelmRateLimitError ← 429
    └── DevhelmServerError    ← 5xx

All classes are importable from the package root:

import {
  DevhelmError,
  DevhelmValidationError,
  DevhelmApiError,
  DevhelmAuthError,
  DevhelmNotFoundError,
  DevhelmConflictError,
  DevhelmRateLimitError,
  DevhelmServerError,
  DevhelmTransportError,
} from "@devhelm/sdk";

DevhelmApiError

The most common error class — thrown for any non-2xx HTTP response.

Property	Type	Description
`status`	`number`	HTTP status code (e.g. `404`)
`code`	`string`	Coarse machine-readable category from `ErrorResponse.code` (e.g. `"NOT_FOUND"`). Defaults to `"API_ERROR"` if the server didn’t supply one.
`message`	`string`	Human-readable message — for logs and user-facing copy
`detail`	`string \| undefined`	Additional context, when available
`body`	`ErrorResponse \| undefined`	Parsed canonical error envelope if the body matched the contract
`rawBody`	`unknown`	Raw response body for debugging non-conforming responses
`requestId`	`string \| undefined`	Per-request id from the `X-Request-Id` header. Always include in support tickets.
`retryAfter`	`number \| undefined`	Seconds from the `Retry-After` header, when present (429)

import { DevhelmApiError } from "@devhelm/sdk";

try {
  await client.monitors.get("missing");
} catch (err) {
  if (err instanceof DevhelmApiError) {
    console.error(err.status);    // 404
    console.error(err.code);      // "NOT_FOUND"
    console.error(err.requestId); // "req_01HJV..."
  }
}

DevhelmValidationError

Thrown before HTTP I/O when a request body fails the Zod schema, and after a successful response when the response body doesn’t match the expected schema (rare — usually indicates a stale SDK).

Property	Type	Description
`message`	`string`	Summary of the first 5 issues
`issues`	`ReadonlyArray<ValidationIssue>`	Structured issues with `path`, `message`, and `code`

import { DevhelmValidationError } from "@devhelm/sdk";

try {
  await client.monitors.create({ type: "HTTP" } as any); // missing fields
} catch (err) {
  if (err instanceof DevhelmValidationError) {
    for (const issue of err.issues) {
      console.error(`${issue.path.join(".")}: ${issue.message}`);
    }
  }
}

DevhelmTransportError

Thrown for network-level failures (connection refused, DNS, TLS handshake, timeout). The original fetch error is on .cause.

import { DevhelmTransportError } from "@devhelm/sdk";

try {
  await client.monitors.list();
} catch (err) {
  if (err instanceof DevhelmTransportError) {
    console.error("Network error:", err.message);
    console.error("Underlying:", err.cause);
  }
}

Handling patterns

Catch by HTTP class

import {
  DevhelmAuthError,
  DevhelmNotFoundError,
  DevhelmRateLimitError,
  DevhelmError,
} from "@devhelm/sdk";

try {
  const monitor = await client.monitors.get(monitorId);
} catch (err) {
  if (err instanceof DevhelmAuthError) {
    console.error("Bad token or insufficient permissions");
  } else if (err instanceof DevhelmNotFoundError) {
    console.error(`Monitor ${monitorId} no longer exists`);
  } else if (err instanceof DevhelmRateLimitError) {
    console.error(`Rate limited (request_id=${err.requestId})`);
  } else if (err instanceof DevhelmError) {
    throw err;
  }
}

Retry on rate limits and 5xx

import {
  DevhelmRateLimitError,
  DevhelmServerError,
  DevhelmTransportError,
} from "@devhelm/sdk";

async function withRetry<T>(
  fn: () => Promise<T>,
  { maxRetries = 3, baseDelayMs = 1000 } = {},
): Promise<T> {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (err) {
      const retryable =
        err instanceof DevhelmRateLimitError ||
        err instanceof DevhelmServerError ||
        err instanceof DevhelmTransportError;
      if (!retryable || attempt === maxRetries) throw err;
      const delay = baseDelayMs * Math.pow(2, attempt);
      await new Promise((r) => setTimeout(r, delay));
    }
  }
  throw new Error("unreachable");
}

const monitors = await withRetry(() => client.monitors.list());

Don’t retry on DevhelmValidationError, DevhelmAuthError, DevhelmNotFoundError, or DevhelmConflictError — these are deterministic and won’t change without code or config changes.

Deploy lock contention

import { DevhelmConflictError } from "@devhelm/sdk";

try {
  const lock = await client.deployLock.acquire({
    lockedBy: "ci-pipeline",
    ttlMinutes: 30,
  });
} catch (err) {
  if (err instanceof DevhelmConflictError) {
    const current = await client.deployLock.current();
    console.error(`Lock held by ${current?.lockedBy} (since ${current?.lockedAt})`);
  }
}

Catch-all logging

import { DevhelmApiError, DevhelmError } from "@devhelm/sdk";

try {
  await doWork(client);
} catch (err) {
  if (err instanceof DevhelmApiError) {
    log.error("DevHelm API error", {
      status: err.status,
      code: err.code,
      requestId: err.requestId,
      detail: err.detail,
    });
  } else if (err instanceof DevhelmError) {
    log.error("DevHelm SDK error", { message: err.message });
  } else {
    throw err;
  }
}

Wait timeouts

client.inboxes.wait, inbox.wait, client.email.wait, and address.wait hold the request open until a match arrives. These are the errors they and the other testing calls throw:

Status	Class	Check	Meaning
408	`DevhelmApiError` (no subclass)	`err.code === "WAIT_TIMEOUT"`	Nothing matched before `timeoutMs`. Often `receivedAfter` was taken after the item arrived
429	`DevhelmRateLimitError`	`err.retryAfter` (seconds)	Over 40 waits per minute. The budget is shared by every wait in the organization, inboxes and email
403	`DevhelmAuthError`	`err.code`, for example `INBOUND_EVENTS_MONTHLY_LIMIT_REACHED`	A testing plan quota on create or inject, not a bad key

There is no timeout subclass. A 408 is a plain DevhelmApiError, so check code, and test for DevhelmRateLimitError first.
The SDK does not retry. Retrying a wait is safe: wait does not consume, so the same receivedAfter finds the same item.
The HTTP call is aborted 10 seconds after timeoutMs, so the 408 arrives first. Set your test runner’s timeout above timeoutMs.

import {
  DevhelmApiError,
  DevhelmRateLimitError,
  type Event,
  type WaitInboxOptions,
} from "@devhelm/sdk";

/** The matching event, or null if none arrived before the timeout. */
async function waitOrNull(inboxId: string, opts: WaitInboxOptions): Promise<Event | null> {
  for (let attempt = 1; ; attempt++) {
    try {
      return await client.inboxes.wait(inboxId, opts);
    } catch (err) {
      if (err instanceof DevhelmRateLimitError && attempt < 3) {
        await new Promise((resolve) => setTimeout(resolve, (err.retryAfter ?? 5) * 1000));
        continue;
      }
      if (err instanceof DevhelmApiError && err.code === "WAIT_TIMEOUT") return null;
      throw err;
    }
  }
}

// Negative assertion: a cancelled order must not send a webhook.
const since = new Date().toISOString();
await cancelOrder(42);
const event = await waitOrNull(inboxId, { receivedAfter: since, timeoutMs: 10_000 });
if (event !== null) throw new Error(`unexpected webhook to ${event.path}`);

A negative assertion spends one wait from the shared budget. Give it a timeout that covers your sender’s latency plus a few seconds of storage lag. See Wait for a webhook in a test and Limits, quotas, and errors.

Overview

TypeScript SDK

Python SDK

MCP Server

AI Skills

TypeScript Error Handling

Error class hierarchy

DevhelmApiError

DevhelmValidationError

DevhelmTransportError

Handling patterns

Catch by HTTP class

Retry on rate limits and 5xx

Deploy lock contention

Catch-all logging

Wait timeouts

Next steps

Pagination

Error patterns

​Error class hierarchy

​DevhelmApiError

​DevhelmValidationError

​DevhelmTransportError

​Handling patterns

​Catch by HTTP class

​Retry on rate limits and 5xx

​Deploy lock contention

​Catch-all logging

​Wait timeouts

​Next steps

Pagination

Error patterns

Error class hierarchy

DevhelmApiError

DevhelmValidationError

DevhelmTransportError

Handling patterns

Catch by HTTP class

Retry on rate limits and 5xx

Deploy lock contention

Catch-all logging

Wait timeouts

Next steps