Errors

The SDK throws three types of errors: APIError for API failures, ValidationError for transaction protection limits and SigningError for transaction signing issues.

Error Types

import { APIError, ValidationError, SigningError } from '@darkfibre/sdk';

APIError

Thrown when the API returns an error response.

class APIError extends Error {
  code: string;    // Error code (e.g., "INSUFFICIENT_BALANCE")
  message: string; // Human-readable message
  status: number;  // HTTP status code
}

ValidationError

Thrown when trade limits are exceeded (e.g., price impact or priority cost exceeds your specified maximums).

class ValidationError extends Error {
  field?: string;  // Field that failed validation (e.g., "maxPriceImpact", "maxPriorityCost")
  message: string; // Validation error message
}

Common scenarios:

maxPriceImpact exceeded: The trade’s price impact is higher than your specified limit
maxPriorityCost exceeded: The priority fee is higher than your specified maximum

SigningError

Thrown when transaction signing fails. This error should not occur if you’re using a valid private key in the correct format.

class SigningError extends Error {
  cause?: Error;   // Underlying error that caused the signing failure
  message: string; // Signing error message
}

Note: If you encounter a SigningError, verify that:

Your private key is base58-encoded
The key length is either 32 bytes (private key only) or 64 bytes (full keypair)
The private key format matches your wallet provider (e.g., Phantom, Solflare)

When using the SDK with a correct private key, signing errors should not occur under normal circumstances.

Basic Error Handling

import { DarkfibreSDK, APIError, ValidationError, SigningError } from '@darkfibre/sdk';

const sdk = new DarkfibreSDK({
  apiKey: 'your-api-key',
  privateKey: 'your-base58-private-key',
});

try {
  const result = await sdk.buy({
    mint: 'token-mint-address',
    solAmount: 0.01,
    slippage: 0.05,
    priority: 'fast',
  });

  console.log('Success:', result.signature);

} catch (error) {
  if (error instanceof ValidationError) {
    console.error(`Validation error: ${error.message}`);
    // Limit exceeded (e.g., maxPriceImpact or maxPriorityCost)
  } else if (error instanceof SigningError) {
    console.error(`Signing error: ${error.message}`);
    // This should not happen with a correct private key
  } else if (error instanceof APIError) {
    console.error(`API error [${error.code}]: ${error.message}`);
  } else {
    throw error;
  }
}

Common API Errors

Code	Action
`AUTH_ERROR`	Verify `Authorization: Bearer api_...`
`VALIDATION_ERROR`	Validate request body (mints/amounts/slippage)
`INSUFFICIENT_FUNDS`	Check wallet balance (not enough SOL or tokens for transaction)
`INSUFFICIENT_SOL`	Add SOL to wallet (not enough for transaction fees)
`INSUFFICIENT_TOKEN_BALANCE`	Check token balance (not enough tokens to sell)
`SLIPPAGE_EXCEEDED`	Try increasing priority or slippage
`RATE_LIMIT_EXCEEDED`	Too many RPC requests, wait and retry
`TX_EXPIRED`	Rebuild the transaction and submit quicker
`CONFLICT_ERROR`	Wallet already registered, use existing API key

API Errors