Error codes

Every non-2xx response throws BoardApiError. The client preserves the API’s machine code, human message, structured details, request ID, HTTP status, and parsed raw body.

1234567
class BoardApiError extends Error {
  status: number;
  code: BoardApiErrorCode;
  details?: unknown;
  requestId?: string;
  raw: unknown;
}

If the response is not a parseable Cavuno error envelope, the SDK synthesizes unknown_error and retains the parsed body when one exists.

Handle an error once

12345678910111213141516171819202122232425262728293031323334
import {
  isBoardApiError,
  isBoardPasswordRequired,
  isNotFound,
  isRateLimited,
  isUnauthorized,
} from '@cavuno/board';

export async function loadJob(jobSlug: string) {
  try {
    return { state: 'ready' as const, job: await board.jobs.retrieve(jobSlug) };
  } catch (error) {
    if (isBoardPasswordRequired(error)) {
      return { state: 'board_password_required' as const };
    }

    if (isUnauthorized(error)) {
      return { state: 'session_expired' as const };
    }

    if (isNotFound(error)) return { state: 'not_found' as const };
    if (isRateLimited(error)) return { state: 'retry_later' as const };

    if (isBoardApiError(error)) {
      console.error({
        code: error.code,
        status: error.status,
        requestId: error.requestId,
      });
    }

    throw error;
  }
}

Catch an error where the interface can make a recovery decision. Do not turn every error into an empty list.

Guards

The guards are structural rather than instanceof-only so they remain correct when separate helper bundles contain their own class copy.

Complete known-code catalog

This is the complete exported BOARD_API_ERROR_CODES catalog in version 1.34.0. Codes can be added compatibly within API v1, so a default branch remains mandatory.

Retry rules

The SDK performs exactly one fetch for every method call.

• Public reads can be retried by the host with bounded backoff after 429 or transient 5xx/search failures.
• A 401 refresh is explicit because refresh tokens rotate. Coordinate one refresh, persist the new pair, then retry the owning read once.
• Do not retry validation, permission, not-found, plan, quota, or conflict errors until input or server state changes.
• Do not blanket-retry writes. Some individual operations converge or support a specific retry contract, but the SDK provides no global mutation idempotency promise.
• For a network failure after a write, the result can be unknown. Re-read state before offering another submission.

Observability and user copy

Use code for control flow and translation lookup. The server’s message is useful for diagnostics but is not a stable localization key. Treat details as unknown until narrowed for the specific code.

Log code, status, requestId, route or operation name, and non-sensitive context. Never log access tokens, password grants, resumes, application content, messages, checkout secrets, or the entire raw body by default.

Verify error handling

Request a known missing resource in development. Confirm that the UI reaches the 404 branch and the diagnostic event contains the server request ID when one was returned. Then simulate an unknown code and confirm the default branch remains reachable.