error-handling.md

← Back to index

Error Handling

The SDK uses ConnectRPC. Errors are thrown as ConnectError instances from the @connectrpc/connect package.

import { ConnectError } from "@connectrpc/connect";

try {
  await client.monitor.v1.MonitorService.deleteMonitor({ id: "invalid" });
} catch (error) {
  if (error instanceof ConnectError) {
    console.error(`Code: ${error.code}`);
    console.error(`Message: ${error.message}`);
  }
}

Common Error Codes

Code	Description
unauthenticated	Missing or invalid API key
not_found	Resource does not exist
invalid_argument	Validation failure (e.g., missing required field, value out of range)
permission_denied	No access to this workspace or resource
already_exists	Duplicate resource (e.g., slug already taken)

Retry Strategy

ConnectRPC does not retry by default. For transient failures (unavailable, deadline_exceeded), implement your own retry logic:

import { ConnectError } from "@connectrpc/connect";

async function withRetry<T>(fn: () => Promise<T>, maxRetries = 3): Promise<T> {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (
        error instanceof ConnectError &&
        (error.code === "unavailable" || error.code === "deadline_exceeded") &&
        attempt < maxRetries
      ) {
        await new Promise((resolve) =>
          setTimeout(resolve, 1000 * 2 ** attempt)
        );
        continue;
      }
      throw error;
    }
  }
  throw new Error("Unreachable");
}

const { httpMonitors } = await withRetry(() =>
  client.monitor.v1.MonitorService.listMonitors({})
);