Error Handling

StarkfiError

All errors in StarkFi use the custom StarkfiError class. Every error carries a typed ErrorCode, a human-readable message, and optional structured details:

class StarkfiError extends Error {
	constructor(
		public readonly code: ErrorCode,
		message: string,
		public readonly details?: unknown,
		options?: { cause?: unknown }
	) {
		super(message, options);
		this.name = "StarkfiError";
	}

	toJSON() {
		return {
			error: true,
			code: this.code,
			message: this.message,
			...(this.details ? { details: this.details } : {}),
		};
	}
}

The toJSON() method ensures errors are consistently serialized in MCP responses and --json CLI output.

Error Codes

StarkFi defines 25 typed error codes organized by domain:

Authentication & Session

Wallet

Transactions

Trading

Staking

Lending

Infrastructure

Validation

General

Starknet Error Parsing

Raw Starknet JSON-RPC errors often contain hex-encoded Cairo short strings (e.g., 0x753235365f737562204f766572666c6f77 → u256_sub Overflow) that are unreadable. The parseStarknetError() utility automatically:

1. Decodes hex-encoded short strings from execution_error payloads
2. Matches known Cairo error patterns against a map of 15 common errors
3. Returns a user-friendly message, or passes through the original if no match is found
4. Strips ENTRYPOINT_FAILED noise from error chains

Error Map (15 patterns)

Integration

• CLI: formatError() in lib/format.ts calls parseStarknetError() before displaying
• MCP: withErrorHandling() in mcp/tools/error-handling.ts calls parseStarknetError() before returning JSON

This ensures both human users and AI agents receive the same readable error messages.

Retry Logic

Network requests use automatic retry with exponential backoff via withRetry():

Only retryable error codes (specified per call via retryOnCodes) trigger retries. Domain errors like INSUFFICIENT_BALANCE or NO_ROUTE_FOUND fail immediately — there's no point retrying when the input is invalid.

Fetch Timeout

All HTTP requests use fetchWithTimeout() which wraps the native fetch() with an AbortController that auto-cancels after 15 seconds by default. This prevents hanging requests from blocking the CLI or MCP server.

Error Handling Patterns

CLI Commands

CLI commands catch errors at the top level, stop the spinner, and print a formatted error message:

try {
	// ... operation
	spinner.succeed("Done");
} catch (error) {
	spinner.fail("Operation failed");
	console.error(formatError(error));
	process.exit(1);
}

MCP Handlers

MCP handlers return errors as structured JSON, allowing AI clients to parse and understand the failure:

{
	"error": true,
	"code": "INSUFFICIENT_BALANCE",
	"message": "Not enough ETH — have 0.01, need 0.1"
}

Simulation Before Execution

Transaction commands support --simulate (CLI) or simulation parameters (MCP) to catch errors before they cost gas. Always simulate first when the outcome is uncertain.