Error Handling

Every SDK rejects with typed errors so you can branch on failure mode instead of parsing strings. The client SDK has the richest hierarchy; the server and MCP packages each have a focused error type.

Client SDK errors

All client errors extend DivinciError, which carries the machine-readable code, the HTTP status, an optional details object, and the requestId for support.

Error	Status	Thrown when
AuthenticationError	401	Invalid, missing, or expired credentials
ValidationError	400	Invalid request parameters (see fieldErrors)
RateLimitError	429	Too many requests (see retryAfter, limit, remaining)
QuotaExceededError	429	Usage quota for the workspace/release is exhausted
PaymentRequiredError	402	An x402-priced resource needs payment
NotFoundError	404	The release, thread, or resource doesn’t exist
NetworkError	—	Connection failed (see retryable)
TimeoutError	—	The request exceeded timeout
StreamError	—	A streaming response failed mid-flight

import {
  DivinciClient,
  RateLimitError,
  QuotaExceededError,
  AuthenticationError,
  PaymentRequiredError,
} from "@divinci-ai/client";

try {
  await client.chat.send(thread.id, "Hello!", { assistantName: "your-assistant-id" });
} catch (error) {
  if (error instanceof RateLimitError) {
    // Back off using the server-provided hint
    await sleep((error.retryAfter ?? 1) * 1000);
    return retry();
  }

  if (error instanceof QuotaExceededError) {
    showUpgradePrompt();
    return;
  }

  if (error instanceof AuthenticationError) {
    redirectToLogin();
    return;
  }

  if (error instanceof PaymentRequiredError) {
    // amount + payment URL are available on the error
    openCheckout(error.getPaymentUrl(), error.getAmountUsd());
    return;
  }

  throw error; // unknown — let it bubble
}

Inspecting an error

Every DivinciError serializes cleanly for logging:

import { DivinciError } from "@divinci-ai/client";

try {
  await client.chat.create();
} catch (error) {
  if (error instanceof DivinciError) {
    console.error(error.toJSON()); // { code, status, details, requestId, message }
  }
}

Tip

Catch the most specific error first, then fall back to DivinciError, then rethrow anything you don’t recognize. Swallowing unknown errors hides bugs.

Server SDK errors

The server SDK throws ServerApiError for any non-2xx API response. It exposes the same fields — code, status, details, requestId, plus the raw body.

import { ServerApiError } from "@divinci-ai/server";

try {
  await divinci.workspaces.get("ws_missing");
} catch (error) {
  if (error instanceof ServerApiError) {
    if (error.status === 404) {
      // handle not found
    }
    console.error(error.code, error.requestId);
  }
}

MCP SDK errors

Paid tool calls throw PaymentRequiredError (carrying paymentDetails) when no valid payment accompanies the request. See MCP x402 Payments for the autopay and manual-retry patterns.

Retry guidance

• NetworkError — retry only if error.retryable is true.
• RateLimitError — honor retryAfter; use exponential backoff if absent.
• TimeoutError — safe to retry idempotent reads; be careful retrying sends.
• AuthenticationError / ValidationError — never retry blindly; fix the cause.

The SDKs already retry transient failures internally up to maxRetries (default 3). Tune it per client via the constructor, or pass skipRetry on an individual request through the underlying HTTP client.