SDK errors

Every @buckt/sdk method throws a typed subclass of BucktError on non-2xx responses. Use instanceof to discriminate — every error class is a named export from @buckt/sdk.

Error classes

Class	HTTP status	When thrown
`BucktError`	—	Base class. All other SDK errors extend it. Catch this if you want a single fallback.
`ValidationError`	400	Request body, query, or path parameters failed server-side validation. The message describes the offending field.
`UnauthorizedError`	401	The `Authorization` header was missing, malformed, the key doesn't exist, or it's past its `expiresAt`.
`PaymentRequiredError`	402	The action exceeds your plan's limits (e.g. too many buckets, too much storage, optimization on the free plan).
`ForbiddenError`	403	The key is valid but missing a required permission scope, or scoped to different bucket ids.
`NotFoundError`	404	The target resource doesn't exist, or the key can't see it (bucket-scoped keys hide other buckets behind 404).
`TimeoutError`	408	The server didn't finish processing within the request timeout. Safe to retry idempotent calls.
`ConflictError`	409	A uniqueness or state constraint failed (duplicate domain, deleting a non-empty bucket, etc.).
`RateLimitError`	429	Too many requests. Back off and retry.

Every error carries message (string) and status (number). The cause property is set to the underlying fetch error or response body when available, so JSON.parse(error.cause as string) may yield the original API error envelope on transport failures.

Handling errors

buckt-with-errors.ts

import {
  Buckt,
  ConflictError,
  NotFoundError,
  RateLimitError,
  UnauthorizedError,
  ValidationError,
} from "@buckt/sdk";

const client = new Buckt({ apiKey: process.env.BUCKT_API_KEY! });

try {
  const bucket = await client.buckets.get("bkt_does_not_exist");
  console.log(bucket.name);
} catch (err) {
  if (err instanceof NotFoundError) {
    // 404 — the bucket id doesn't exist (or your key can't see it).
    return null;
  }
  if (err instanceof UnauthorizedError) {
    // 401 — the key is missing, malformed, or expired.
    throw new Error("Refresh BUCKT_API_KEY", { cause: err });
  }
  if (err instanceof RateLimitError) {
    // 429 — back off and retry.
  }
  if (err instanceof ConflictError || err instanceof ValidationError) {
    // 409 / 400 — caller error.
  }
  throw err;
}

For network failures (DNS, refused connections, aborted requests) the SDK re-throws the underlying fetch error unchanged — those are not BucktError instances. Wrap your top-level call in a generic catch when network resilience matters.