Errors and recovery

Catch Enlitt errors around the model operation. Specific classes are exported from @enlitt/sdk/core, with compatibility exports from @enlitt/sdk/server. Use the stable code for diagnosis, and show users a message they can act on.

User actions

Login errors direct users to your login route. The four spending/credit codes spending_limit_exceeded, premium_balance_exhausted, standard_balance_exhausted, and subscription_inactive may carry authorizeUrl. It is optional; do not assume every refusal includes a link.

Integration problems

Keep configuration and authentication details in your business logs. Show a generic service error to the user. Never log a secret or session token.

Example recovery

This server-side helper returns a simple result your UI can render:

import {
  EnlittLoginRequiredError,
  EnlittLimitExceededError,
  EnlittInsufficientCreditsError,
  EnlittSubscriptionInactiveError
} from "@enlitt/sdk/core";

export async function runForUser<T>(run: () => Promise<T>) {
  try {
    return { ok: true as const, value: await run() };
  } catch (error) {
    if (error instanceof EnlittLoginRequiredError) {
      return {
        ok: false as const,
        message: "Sign in with Enlitt to continue.",
        href: "/auth/enlitt/login"
      };
    }
    if (
      error instanceof EnlittLimitExceededError ||
      error instanceof EnlittInsufficientCreditsError ||
      error instanceof EnlittSubscriptionInactiveError
    ) {
      return {
        ok: false as const,
        message: "Review your Enlitt spending settings or credits.",
        href: error.authorizeUrl
      };
    }
    throw error; // Let your server's error handler log and handle other failures.
  }
}

Retry behavior

Admission refusals such as login, spending, and exhausted-credit errors are non-retryable. Repeating them cannot repair the user's account or settings. EnlittRateLimitError (rate_limit_exceeded) is retryable and can carry retryAfterMs. The SDK handles bounded rate-limit waiting; the defaults are three attempts and a 30-second total wait budget. Set rateLimit: { maxAttempts: 1 } to handle that wait yourself.

The codes server_error and provider_error also have a retryable marker. The marker does not mean every SDK adapter automatically retries them. Keep the same idempotency identity when retrying a logical call.

Other Enlitt failures use the base EnlittError shape with their stable code, including unknown codes from newer servers. Leave a fallback in code-based handling. The base is documented as a type; use the named runtime subclasses in examples. A premium provider's own errors are rethrown unchanged.

Terminal-report failures go to onTerminalReportError; they do not replace successful provider output. Monitor that hook separately from user-facing failures.