Errors

Typed error classes for authentication, quota, rate limiting, and transport failures.

Every SDK call throws a typed error on failure. Handle them in a typed catch to react appropriately.

import {
  DuckvizError,
  DuckvizAuthError,
  DuckvizQuotaExceededError,
  DuckvizRateLimitError,
  DuckvizServerError,
  DuckvizNetworkError,
} from "@duckviz/sdk";

try {
  await widgetFlow.invoke(input);
} catch (e) {
  if (e instanceof DuckvizAuthError) {
    console.error("Check your API token");
  } else if (e instanceof DuckvizQuotaExceededError) {
    console.error("Buy more credits");
  } else if (e instanceof DuckvizRateLimitError) {
    console.error("Slow down, retry after:", e.retryAfter);
  } else if (e instanceof DuckvizServerError) {
    console.error("Server-side failure, try again later");
  } else if (e instanceof DuckvizNetworkError) {
    console.error("Network failure — no response received");
  }
}

Error class reference

Class	Status	When it fires
`DuckvizAuthError`	`401`	Token missing, expired, or revoked.
`DuckvizQuotaExceededError`	`402`	No credits remaining.
`DuckvizRateLimitError`	`429`	Too many requests per window. Includes `retryAfter` (seconds).
`DuckvizServerError`	`5xx`	Server-side error. Automatically retried up to `maxRetries`.
`DuckvizNetworkError`	—	Transport failure with no HTTP response (DNS, TCP reset, timeout).
`DuckvizError`	—	Base class. All of the above extend it.

DuckvizServerError and DuckvizNetworkError are retried automatically with exponential backoff, capped at maxRetries (default 3). DuckvizAuthError, DuckvizQuotaExceededError, and DuckvizRateLimitError are not retried — they're treated as definitive.

Override retries per class:

const sdk = new DuckvizWidgetFlow({ token, maxRetries: 0 });

Error class reference

Retry semantics

On this page