error-handling

Error Handling

Custom Errors vs Require Strings

Custom errors are cheaper and more expressive. Always prefer them.

// BAD: require with string (~200 gas more per revert, larger bytecode)
require(amount > 0, "Amount must be greater than zero");
require(msg.sender == owner, "Not authorized");

// GOOD: custom errors
error ZeroAmount();
error Unauthorized(address caller, address required);

if (amount == 0) revert ZeroAmount();
if (msg.sender != owner) revert Unauthorized(msg.sender, owner);

Gas Comparison

Pattern	Deploy Cost	Revert Cost
require("string")	+~200 bytes	~2,400 gas
revert CustomError()	+~4 bytes	~2,200 gas
revert CustomError(param)	+~4 bytes	~2,300 gas

Error Hierarchy Design

Organize errors by domain for large protocols. Prefix with the contract or module name for clarity in offchain decoding.

// errors/VaultErrors.sol
interface VaultErrors {
    error Vault_InsufficientBalance(address user, uint256 available, uint256 requested);
    error Vault_DepositCapExceeded(uint256 cap, uint256 attempted);
    error Vault_WithdrawalPaused();
    error Vault_InvalidToken(address token);
    error Vault_SlippageExceeded(uint256 expected, uint256 actual);
}

// errors/OracleErrors.sol
interface OracleErrors {
    error Oracle_StalePrice(address feed, uint256 updatedAt, uint256 threshold);
    error Oracle_InvalidRound(uint80 roundId);
    error Oracle_NegativePrice(int256 price);
    error Oracle_ZeroPrice();
}

// Inherit in implementation
contract Vault is VaultErrors, OracleErrors {
    function withdraw(uint256 amount) external {
        uint256 balance = balances[msg.sender];
        if (balance < amount) {
            revert Vault_InsufficientBalance(msg.sender, balance, amount);
        }
        // ...
    }
}

Try/Catch for External Calls

Use try/catch when you need to handle failures from external contract calls gracefully.

interface IPriceFeed {
    function latestRoundData() external view returns (
        uint80 roundId, int256 answer, uint256 startedAt,
        uint256 updatedAt, uint80 answeredInRound
    );
}

function getPrice(IPriceFeed feed) internal view returns (uint256) {
    try feed.latestRoundData() returns (
        uint80, int256 answer, uint256, uint256 updatedAt, uint80
    ) {
        if (answer <= 0) revert Oracle_NegativePrice(answer);
        if (block.timestamp - updatedAt > STALENESS_THRESHOLD) {
            revert Oracle_StalePrice(address(feed), updatedAt, STALENESS_THRESHOLD);
        }
        return uint256(answer);
    } catch Error(string memory reason) {
        // Catches require() / revert("string") failures
        revert OracleCallFailed(reason);
    } catch (bytes memory lowLevelData) {
        // Catches custom errors, panics, or out-of-gas
        revert OracleCallFailedBytes(lowLevelData);
    }
}