Error Handling

VerityError (base)
  ├── VerityApiError           — non-2xx API response
  ├── LeaseConflictError       — 409, another agent holds the lease
  ├── EffectPreviouslyFailedError — effect already failed, reset required
  ├── CommitUncertainError     — action succeeded, commit failed (CRITICAL)
  ├── VerityConfigError        — missing required config
  └── VerityValidationError    — input data invalid or too large

// TypeScript
import { CommitUncertainError } from '@verityinc/sdk';

try {
  await verity.protect('charge:order_123', {
    act: () => stripe.charges.create({ amount: 5000 }),
  });
} catch (error) {
  if (error instanceof CommitUncertainError) {
    // 1. HALT — do not retry protect()
    // 2. Log the result for manual reconciliation
    console.error(`CRITICAL: Action succeeded for ${error.effectKey}`);
    console.error(`Result: ${JSON.stringify(error.result)}`);
    console.error(`Commit error: ${error.commitError}`);

    // 3. Alert your ops team
    alertOpsTeam({
      type: 'commit_uncertain',
      effectKey: error.effectKey,
      result: error.result,
    });

    // 4. Check Explorer UI or query API to reconcile
    // The effect may show as RUNNING (lease active) or will
    // eventually expire. An admin can manually commit or reset.
  }
}

# Python
from verity import CommitUncertainError

try:
    await verity.protect("charge:order_123", act=execute_charge)
except CommitUncertainError as e:
    logger.critical(
        f"CRITICAL: Action succeeded for {e.effect_key}. "
        f"Result: {e.result}. Commit error: {e.commit_error}"
    )
    alert_ops_team(e)
    # DO NOT RETRY — check Explorer to reconcile

import { LeaseConflictError } from '@verityinc/sdk';

try {
  await verity.protect('charge:order_123', { act: chargeCustomer }, {
    onConflict: 'throw',  // don't retry, fail fast
  });
} catch (error) {
  if (error instanceof LeaseConflictError) {
    // Another agent is handling this effect — safe to back off
    console.log(`Effect ${error.effectKey} is being processed elsewhere`);
  }
}

import { EffectPreviouslyFailedError } from '@verityinc/sdk';

try {
  await run.protect('process_refund', { act: executeRefund });
} catch (error) {
  if (error instanceof EffectPreviouslyFailedError) {
    console.log(`Effect ${error.effectKey} previously failed:`, error.cachedError);
    // Options:
    // 1. Log and alert — wait for admin to reset in Explorer
    // 2. Programmatically reset via the admin API (if you have org_admin key)
    // 3. Skip this step and continue with a fallback
  }
}

import {
  VerityError,
  CommitUncertainError,
  EffectPreviouslyFailedError,
  LeaseConflictError,
  VerityApiError,
} from '@verityinc/sdk';

async function safeProtect() {
  try {
    return await verity.protect('charge:order_123', {
      observe: checkExistingCharge,
      act: executeCharge,
    });
  } catch (error) {
    // Priority 1: Commit uncertainty — the action happened
    if (error instanceof CommitUncertainError) {
      await alertOpsTeam('commit_uncertain', error);
      throw error; // Don't swallow — caller must know
    }

    // Priority 2: Previously failed — needs admin reset
    if (error instanceof EffectPreviouslyFailedError) {
      logger.warn(`Effect ${error.effectKey} needs reset: ${error.cachedError}`);
      throw error;
    }

    // Priority 3: Lease conflict — another agent is on it
    if (error instanceof LeaseConflictError) {
      logger.info(`Effect ${error.effectKey} is being handled elsewhere`);
      return null; // or throw, depending on your use case
    }

    // Priority 4: API errors
    if (error instanceof VerityApiError) {
      logger.error(`Verity API error ${error.statusCode}:`, error.body);
      throw error;
    }

    // Priority 5: Any other Verity error
    if (error instanceof VerityError) {
      logger.error('Verity error:', error.message);
      throw error;
    }

    // Priority 6: Non-Verity error (your act() threw)
    throw error;
  }
}