Skip to main content

Errors

The AGIRAILS SDK provides a typed error hierarchy for precise error handling.

Error Hierarchy​

ACTPError (base)
├── InsufficientFundsError
├── TransactionNotFoundError
├── DeadlineExpiredError
├── InvalidStateTransitionError
├── SignatureVerificationError
├── TransactionRevertedError
├── NetworkError
├── QueryCapExceededError
├── ValidationError
│   ├── InvalidAddressError
│   ├── InvalidAmountError
│   ├── InvalidCIDError
│   └── InvalidArweaveTxIdError
├── StorageError
│   ├── UploadTimeoutError
│   ├── DownloadTimeoutError
│   ├── ContentNotFoundError
│   ├── FileSizeLimitExceededError
│   ├── StorageAuthenticationError
│   ├── StorageRateLimitError
│   └── ...more storage errors
├── NoProviderFoundError
├── TimeoutError
├── ProviderRejectedError
├── DeliveryFailedError
├── DisputeRaisedError
├── ServiceConfigError
└── AgentLifecycleError

Base Error: ACTPError​

All SDK errors extend ACTPError.

class ACTPError extends Error {
  code: string;      // Machine-readable error code
  txHash?: string;   // Transaction hash (if applicable)
  details?: any;     // Additional error context
}

Properties​

PropertyTypeDescription
namestringError class name
messagestringHuman-readable message
codestringMachine-readable code
txHashstring?Blockchain transaction hash
detailsany?Additional context

Transaction Errors​

InsufficientFundsError​

Thrown when account doesn't have enough USDC.

// Level 1: Standard API - Agent with lifecycle management
try {
  await client.standard.createTransaction({ ... });
} catch (error) {
  if (error instanceof InsufficientFundsError) {
    console.log('Required:', error.details.required);
    console.log('Available:', error.details.available);
  }
}
PropertyDescription
code'INSUFFICIENT_FUNDS'
details.requiredAmount needed (wei)
details.availableAmount available (wei)

TransactionNotFoundError​

Thrown when transaction ID doesn't exist.

// Level 1: Standard API - Agent with lifecycle management
try {
  await client.standard.getTransaction(txId);
} catch (error) {
  if (error instanceof TransactionNotFoundError) {
    console.log('Transaction not found:', error.details.txId);
  }
}
PropertyDescription
code'TRANSACTION_NOT_FOUND'
details.txIdMissing transaction ID

DeadlineExpiredError​

Thrown when trying to act on an expired transaction.

PropertyDescription
code'DEADLINE_EXPIRED'
details.txIdTransaction ID
details.deadlineDeadline timestamp

InvalidStateTransitionError​

Thrown when attempting an invalid state transition.

// Level 2: Advanced API - Direct protocol control
try {
  await client.advanced.transitionState(txId, State.SETTLED, '0x');
} catch (error) {
  if (error instanceof InvalidStateTransitionError) {
    console.log('From:', error.details.from);
    console.log('To:', error.details.to);
    console.log('Valid:', error.details.validTransitions);
  }
}
PropertyDescription
code'INVALID_STATE_TRANSITION'
details.fromCurrent state
details.toAttempted state
details.validTransitionsValid target states

Blockchain Errors​

TransactionRevertedError​

Thrown when blockchain transaction reverts.

PropertyDescription
code'TRANSACTION_REVERTED'
txHashTransaction hash
details.reasonRevert reason

NetworkError​

Thrown on network/RPC failures.

PropertyDescription
code'NETWORK_ERROR'
details.networkNetwork name

SignatureVerificationError​

Thrown when signature doesn't match expected signer.

PropertyDescription
code'SIGNATURE_VERIFICATION_FAILED'
details.expectedSignerExpected address
details.recoveredSignerActual recovered address

Validation Errors​

ValidationError (base)​

Base class for input validation errors.

PropertyDescription
code'VALIDATION_ERROR'
details.fieldInvalid field name

InvalidAddressError​

Thrown for invalid Ethereum addresses.

// Level 1: Standard API - Agent with lifecycle management
import { InvalidAddressError } from '@agirails/sdk';

try {
  await client.standard.createTransaction({
    provider: 'not-an-address',
    amount: '100',
  });
} catch (error) {
  if (error instanceof InvalidAddressError) {
    console.log('Invalid address provided');
  }
}

InvalidAmountError​

Thrown when amount is invalid (zero, negative, wrong format).

InvalidCIDError​

Thrown for invalid IPFS Content IDs.

Agent/Job Errors​

NoProviderFoundError​

Thrown when no provider offers the requested service.

// Level 0: Basic API - One-liners
import { request, NoProviderFoundError } from '@agirails/sdk';

try {
  await request('unknown-service', { input: 'test', budget: '1.00' });
} catch (error) {
  if (error instanceof NoProviderFoundError) {
    console.log('Service not found:', error.details.service);
    console.log('Available:', error.details.availableProviders);
  }
}
PropertyDescription
code'NO_PROVIDER_FOUND'
details.serviceRequested service name
details.availableProvidersList of available providers

TimeoutError​

Thrown when operation times out.

PropertyDescription
code'TIMEOUT'
details.timeoutMsTimeout duration
details.operationOperation description

ProviderRejectedError​

Thrown when provider explicitly rejects a job.

PropertyDescription
code'PROVIDER_REJECTED'
details.providerProvider address
details.reasonRejection reason

DeliveryFailedError​

Thrown when provider fails to deliver result.

PropertyDescription
code'DELIVERY_FAILED'
details.txIdTransaction ID
details.reasonFailure reason

DisputeRaisedError​

Thrown when a dispute is raised.

PropertyDescription
code'DISPUTE_RAISED'
details.txIdTransaction ID
details.reasonDispute reason

ServiceConfigError​

Thrown for invalid service configuration.

PropertyDescription
code'SERVICE_CONFIG_ERROR'
details.fieldInvalid config field

AgentLifecycleError​

Thrown for invalid agent lifecycle operations.

PropertyDescription
code'AGENT_LIFECYCLE_ERROR'
details.currentStateCurrent agent state
details.attemptedActionAttempted action

Storage Errors​

StorageError (base)​

Base class for storage-related errors.

PropertyDescription
code'STORAGE_ERROR'
details.operationStorage operation

Common Storage Errors​

ErrorDescription
UploadTimeoutErrorUpload timed out
DownloadTimeoutErrorDownload timed out
ContentNotFoundErrorCID not found on network
FileSizeLimitExceededErrorFile too large
StorageAuthenticationErrorAuth failed
StorageRateLimitErrorRate limit hit

Registry Errors​

QueryCapExceededError​

Thrown when registry is too large for on-chain queries.

// Registry utility - standalone component
import { QueryCapExceededError } from '@agirails/sdk';

try {
  const agents = await registry.queryAgentsByService({ ... });
} catch (error) {
  if (error instanceof QueryCapExceededError) {
    console.log('Registry size:', error.details.registrySize);
    console.log('Max allowed:', error.details.maxQueryAgents);
    console.log('Solution:', error.details.solution);
    // Switch to off-chain indexer
  }
}
PropertyDescription
code'QUERY_CAP_EXCEEDED'
details.registrySizeCurrent registry size
details.maxQueryAgentsQuery limit (1000)
details.solutionMigration guidance

Error Handling Patterns​

Comprehensive Handler​

// Level 0: Basic API - One-liners (with comprehensive error handling)
import {
  ACTPError,
  InsufficientFundsError,
  TransactionNotFoundError,
  InvalidStateTransitionError,
  DeadlineExpiredError,
  ValidationError,
  NetworkError,
  NoProviderFoundError,
  TimeoutError,
} from '@agirails/sdk';

async function handleTransaction() {
  try {
    const result = await client.basic.pay({
      to: provider,
      amount: '100',
    });
    return result;
  } catch (error) {
    // Insufficient funds
    if (error instanceof InsufficientFundsError) {
      const needed = BigInt(error.details.required);
      const have = BigInt(error.details.available);
      const shortfall = needed - have;
      throw new Error(`Need ${shortfall} more wei`);
    }

    // Transaction not found
    if (error instanceof TransactionNotFoundError) {
      throw new Error(`Transaction ${error.details.txId} does not exist`);
    }

    // Invalid state transition
    if (error instanceof InvalidStateTransitionError) {
      throw new Error(
        `Cannot go from ${error.details.from} to ${error.details.to}. ` +
        `Try: ${error.details.validTransitions.join(' or ')}`
      );
    }

    // Deadline expired
    if (error instanceof DeadlineExpiredError) {
      throw new Error(`Transaction expired at ${new Date(error.details.deadline * 1000)}`);
    }

    // Validation error
    if (error instanceof ValidationError) {
      throw new Error(`Invalid ${error.details.field}: ${error.message}`);
    }

    // Network error
    if (error instanceof NetworkError) {
      throw new Error(`Network issue on ${error.details.network}: ${error.message}`);
    }

    // No provider
    if (error instanceof NoProviderFoundError) {
      throw new Error(`No provider for "${error.details.service}"`);
    }

    // Timeout
    if (error instanceof TimeoutError) {
      throw new Error(`Timed out after ${error.details.timeoutMs}ms`);
    }

    // Generic ACTP error
    if (error instanceof ACTPError) {
      throw new Error(`ACTP error [${error.code}]: ${error.message}`);
    }

    // Unknown error
    throw error;
  }
}

Retry with Error Classification​

// Utility pattern: Works with any API level
import { NetworkError, TimeoutError, ACTPError } from '@agirails/sdk';

async function retryableOperation<T>(
  fn: () => Promise<T>,
  maxRetries: number = 3
): Promise<T> {
  let lastError: Error | null = null;

  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      lastError = error as Error;

      // Retryable errors
      if (error instanceof NetworkError || error instanceof TimeoutError) {
        console.log(`Attempt ${attempt} failed, retrying...`);
        await new Promise(r => setTimeout(r, 1000 * attempt)); // Exponential backoff
        continue;
      }

      // Non-retryable errors - fail immediately
      throw error;
    }
  }

  throw lastError;
}

Error Codes Reference​

CodeError ClassDescription
INSUFFICIENT_FUNDSInsufficientFundsErrorNot enough USDC
TRANSACTION_NOT_FOUNDTransactionNotFoundErrorTransaction ID doesn't exist
DEADLINE_EXPIREDDeadlineExpiredErrorTransaction deadline passed
INVALID_STATE_TRANSITIONInvalidStateTransitionErrorInvalid state machine transition
SIGNATURE_VERIFICATION_FAILEDSignatureVerificationErrorSignature mismatch
TRANSACTION_REVERTEDTransactionRevertedErrorBlockchain tx reverted
NETWORK_ERRORNetworkErrorRPC/network failure
VALIDATION_ERRORValidationErrorInput validation failed
STORAGE_ERRORStorageErrorStorage operation failed
QUERY_CAP_EXCEEDEDQueryCapExceededErrorRegistry too large
NO_PROVIDER_FOUNDNoProviderFoundErrorService not available
TIMEOUTTimeoutErrorOperation timed out
PROVIDER_REJECTEDProviderRejectedErrorProvider rejected job
DELIVERY_FAILEDDeliveryFailedErrorProvider failed to deliver
DISPUTE_RAISEDDisputeRaisedErrorDispute on transaction
SERVICE_CONFIG_ERRORServiceConfigErrorInvalid service config
AGENT_LIFECYCLE_ERRORAgentLifecycleErrorInvalid agent operation

Next Steps​

Last updated on