Error Handling

The Conto SDK provides detailed error information to help you handle failures gracefully.

ContoError

SDK failures use the exported ContoError class. It exposes only stable customer-facing metadata:

class ContoError extends Error {
  readonly code: string;
  readonly status: number;
  readonly requestId?: string;
  readonly retryAfter?: number;
  readonly retryGuidance?: string;
  readonly actionUrl?: string;
  readonly fieldErrors?: Array<{ field: string; message: string }>;
  readonly reasons?: string[];
}

For validation failures, fieldErrors identifies recognized request fields with locally generated guidance. The pay() helper preserves allowlisted customer-facing denial reasons. The SDK does not forward arbitrary server details, workflow instructions, or provider diagnostics.

Error Codes

Authentication Errors

Code	Status	Description	Solution
`AUTH_FAILED`	401	Missing, invalid, inactive, revoked, or expired API key	Check key is correct and active
`INSUFFICIENT_SCOPE`	403	Key lacks required permission	Use key with required scope

Payment Errors

Code	Status	Description	Solution
`PAYMENT_DENIED`	403	SDK `pay()` helper saw a denied request	Inspect the request response’s `reasons`
`REQUIRES_APPROVAL`	202	SDK `pay()` helper saw an approval-required request	Wait for human approval
`INSUFFICIENT_BALANCE`	400	Wallet has insufficient funds	Fund the wallet
`EXPIRED`	400	Payment request expired	Request new approval
`NOT_FOUND`	404	Request ID not found	Check the request ID
`INVALID_STATUS`	400	Cannot execute in current status	Check payment status
`NO_WALLET`	400	No wallet assigned	Link a wallet to the agent
`LIMIT_EXCEEDED`	400	Spend limit or balance re-check failed at execution time	Re-request after reducing amount or freeing budget
`WALLET_CONFIG_ERROR`	400	Wallet is not ready for payment execution	Contact your admin
`EXECUTION_UNAVAILABLE`	503	Payment execution is temporarily unavailable	Retry later or contact support
`MANUAL_EXECUTION_REQUIRED`	400	External or smart contract wallets cannot be auto-executed	Use the approve/confirm flow instead
`ALREADY_EXECUTED`	409	This payment request was already executed	Check transaction status instead

A repeated execute call after completion can return 400 INVALID_STATUS; a concurrent execution can return 409 ALREADY_EXECUTED. Both require reading the original request, not sending again. Do not rely on a single HTTP status to identify an earlier successful execution.

Validation Errors

Code	Status	Description	Solution
`VALIDATION_ERROR`	400	Invalid request body	Check request parameters
`INVALID_AMOUNT`	400	Amount must be positive	Use a positive number
`INVALID_ADDRESS`	400	Malformed wallet address	Use valid 0x address (EVM) or base58 address (Solana)
`INVALID_JSON`	400	Malformed request body	Send valid JSON

System Errors

Code	Status	Description	Solution
`RATE_LIMITED`	429	Too many requests	Wait and retry
`TIMEOUT`	0	Request timeout	Retry with longer timeout
`INTERNAL_ERROR`	500	Server error	Retry or contact support

For the full state transition and recovery flow, see Track and recover a payment.

Handling Errors

Basic Error Handling

import { Conto, ContoError } from '@conto_finance/sdk';

try {
  const result = await conto.payments.pay({
    amount: 100,
    recipientAddress: '0x...',
  });
} catch (error) {
  if (error instanceof ContoError) {
    console.error(`Error [${error.code}]:`, error.message);
    console.error('HTTP Status:', error.status);
    if (error.requestId) console.error('Request ID:', error.requestId);
  } else {
    console.error('Unexpected error:', error);
  }
}

Handling Specific Error Codes

try {
  await conto.payments.pay({ ... });
} catch (error) {
  if (error instanceof ContoError) {
    switch (error.code) {
      case 'PAYMENT_DENIED':
        console.log('Payment was denied by policy');
        // Check why it was denied
        break;

      case 'REQUIRES_APPROVAL':
        console.log('Payment needs human approval');
        // Notify approvers
        break;

      case 'INSUFFICIENT_BALANCE':
        console.log('Wallet needs funding');
        // Alert treasury team
        break;

      case 'LIMIT_EXCEEDED':
        console.log('Limit or balance changed before execution');
        // Re-check setup and request a smaller payment
        break;

      case 'RATE_LIMITED':
        console.log('Too many requests. The SDK already retried automatically before throwing.');
        // Back off before issuing more requests.
        break;

      default:
        console.error('Unhandled error:', error.code);
    }
  }
}

Decision And Error Boundaries

Policy denials from payments.request() are normal decision responses with status: "DENIED". Transport, authentication, validation, and execution failures throw ContoError. Use separate request and execute calls when your application needs to handle those outcomes independently. The pay() method throws on denial. For more control, use separate request/execute:

// Request first (never throws for denied payments)
const request = await conto.payments.request({
  amount: 100,
  recipientAddress: '0x...',
});

if (request.status === 'DENIED') {
  console.log('Denied reasons:', request.reasons);
  return null;
}

if (request.status === 'REQUIRES_APPROVAL') {
  console.log('Awaiting approval...');
  return { pending: true, requestId: request.requestId };
}

// Only execute if approved
try {
  return await conto.payments.execute(request.requestId);
} catch (error) {
  if (error instanceof ContoError && error.code === 'INSUFFICIENT_BALANCE') {
    // Balance changed between request and execute
  }
}

Handling Rate Limits

The SDK handles retryable rate limits before throwing (see Retry Strategy). If the request is still rate limited, ContoError.retryAfter may provide a server-supplied delay in seconds. Otherwise, back off on your own schedule. If you need an additional application-level retry after the SDK has exhausted its own, wrap the call and back off on your own schedule:

async function payWithRetry(params: PaymentRequestInput) {
  const maxRetries = 3;

  for (let i = 0; i < maxRetries; i++) {
    try {
      return await conto.payments.pay(params);
    } catch (error) {
      const isRateLimited = error instanceof ContoError && error.code === 'RATE_LIMITED';
      if (isRateLimited && i < maxRetries - 1) {
        const waitTime = error.retryAfter ?? 2 ** i;
        console.log(`Still rate limited. Waiting ${waitTime}s...`);
        await new Promise((r) => setTimeout(r, waitTime * 1000));
        continue;
      }
      throw error;
    }
  }
}

Handling Timeouts

For long-running requests, handle timeouts:

const conto = new Conto({
  apiKey: process.env.CONTO_API_KEY!,
  timeout: 60000  // 60 seconds
});

try {
  await conto.payments.pay({ ... });
} catch (error) {
  if (error.code === 'TIMEOUT') {
    console.log('Request timed out');
    // Don't automatically retry payments - check status first!
    const status = await conto.payments.status(requestId);
    if (status.transaction) {
      console.log('Payment was actually submitted:', status.transaction.txHash);
    }
  }
}

Retry Strategy

Built-in Automatic Retry

The SDK automatically retries transient failures only when repeating the request cannot create an additional side effect. Built-in behavior:

Retries read-only requests up to 3 times on network failures, 429, and 5xx
Retries payment authorization requests with the same stable idempotencyKey
Treats x402 and MPP pre-authorization as retryable, non-mutating policy checks
Respects Retry-After headers from the server
Exponential backoff: 1s → 2s → 4s (capped at 10s)
Never automatically retries payment execution, protocol record calls, or ContoAdmin mutations
Does not retry client errors (4xx except retryable 429 responses) or auth failures

// A stable key protects request creation across retries and process restarts.
const request = await conto.payments.request({
  amount: 100,
  recipientAddress: '0x...',
  idempotencyKey: 'job-123-payment-1',
});

if (request.status === 'APPROVED') {
  try {
    await conto.payments.execute(request.requestId);
  } catch (error) {
    // Execution is not retried automatically. Reconcile before acting again.
    const status = await conto.payments.status(request.requestId);
    console.error(error, status);
  }
}

For workflows that require deterministic recovery, prefer the separate request and execute methods over the pay convenience method so the application retains the requestId.

Custom Retry for Application Logic

For application-level retry logic (e.g., re-requesting after a denial), use a custom wrapper:

async function withRetry<T>(fn: () => Promise<T>, maxRetries = 3, baseDelay = 1000): Promise<T> {
  let lastError: Error;

  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      lastError = error;

      // Don't retry certain errors
      if (error instanceof Error && 'code' in error) {
        const sdkError = error as ContoError;
        if (['AUTH_FAILED', 'PAYMENT_DENIED', 'VALIDATION_ERROR'].includes(sdkError.code)) {
          throw error; // Non-retryable
        }

        if (sdkError.code === 'RATE_LIMITED') {
          const delay = baseDelay * Math.pow(2, i);
          await new Promise((r) => setTimeout(r, delay));
          continue;
        }
      }

      // Exponential backoff for other errors
      const delay = baseDelay * Math.pow(2, i);
      await new Promise((r) => setTimeout(r, delay));
    }
  }

  throw lastError!;
}

// Usage for application-level retries
const result = await withRetry(() =>
  conto.payments.pay({
    amount: 100,
    recipientAddress: '0x...',
  })
);

Logging Errors

async function loggedPayment(params: PaymentRequestInput) {
  try {
    const result = await conto.payments.pay(params);
    console.log('Payment successful', {
      txHash: result.receipt?.txHash,
      amount: result.amount,
    });
    return result;
  } catch (error) {
    if (!(error instanceof ContoError)) throw error;
    console.error('Payment failed', {
      code: error.code,
      status: error.status,
      requestId: error.requestId,
      message: error.message,
    });
    throw error;
  }
}

Best Practices

Always Catch Errors

Never let payment errors crash your application:

// Bad
await conto.payments.pay({ ... });

// Good
try {
  await conto.payments.pay({ ... });
} catch (error) {
  // Handle gracefully
}

Check Specific Error Codes

Don’t just catch generic errors:

// Bad
catch (error) {
  console.log('Something went wrong');
}

// Good
catch (error) {
  if (error.code === 'INSUFFICIENT_BALANCE') {
    // Specific handling
  }
}

Don't Retry Payment Execution

Be careful with retries on payment execution:

// Dangerous - might double-pay
await withRetry(() => conto.payments.execute(requestId));

// Safe - check status first
const status = await conto.payments.status(requestId);
if (!status.transaction) {
  await conto.payments.execute(requestId);
}

Log Safe Error Fields

Log the stable fields needed to investigate a failed request. Do not log request bodies, credentials, arbitrary response objects, or payment context:

catch (error) {
  console.error('Payment error', {
    code: error.code,
    status: error.status,
    message: error.message
  });
}

API foundations

SDK and protocols

Controls and integrations

Tools

Error Handling

ContoError

Error Codes

Authentication Errors

Payment Errors

Validation Errors

System Errors

Handling Errors

Basic Error Handling

Handling Specific Error Codes

Decision And Error Boundaries

Handling Rate Limits

Handling Timeouts

Retry Strategy

Built-in Automatic Retry

Custom Retry for Application Logic

Logging Errors

Best Practices

Next Steps

Examples

API Reference

​ContoError

​Error Codes

​Authentication Errors

​Payment Errors

​Validation Errors

​System Errors

​Handling Errors

​Basic Error Handling

​Handling Specific Error Codes

​Decision And Error Boundaries

​Handling Rate Limits

​Handling Timeouts

​Retry Strategy

​Built-in Automatic Retry

​Custom Retry for Application Logic

​Logging Errors

​Best Practices

​Next Steps

Examples

API Reference

ContoError

Error Codes

Authentication Errors

Payment Errors

Validation Errors

System Errors

Handling Errors

Basic Error Handling

Handling Specific Error Codes

Decision And Error Boundaries

Handling Rate Limits

Handling Timeouts

Retry Strategy

Built-in Automatic Retry

Custom Retry for Application Logic

Logging Errors

Best Practices

Next Steps