Error Codes¶

This reference documents all error codes returned by ACDC APIs, SDKs, and CLI tools.

JSON-RPC Errors¶

Standard JSON-RPC 2.0 error codes:

Code	Name	Description
-32700	Parse error	Invalid JSON
-32600	Invalid request	Missing required fields
-32601	Method not found	Unknown RPC method
-32602	Invalid params	Invalid parameter type or value
-32603	Internal error	Server-side error

ACDC-Specific RPC Errors¶

Code	Name	Description
-32000	Transaction rejected	Transaction validation failed
-32001	Insufficient funds	Account balance too low
-32002	Nonce too low	Transaction nonce already used
-32003	Nonce too high	Gap in transaction nonce sequence
-32004	Gas too low	Gas limit below minimum
-32005	Gas price too low	Gas price below network minimum
-32006	Execution reverted	Contract execution failed
-32007	Block not found	Requested block does not exist
-32008	Transaction not found	Requested transaction does not exist
-32009	Account not found	Address has no on-chain state
-32010	Contract error	Contract-specific error
-32011	Rate limited	Too many requests
-32012	Subscription error	WebSocket subscription failed
-32013	Proof invalid	ZK proof verification failed
-32014	Record spent	Alpha chain record already spent

Transaction Errors¶

Validation Errors¶

Code	Name	Description	Resolution
`TX_INVALID_SIGNATURE`	Invalid signature	Signature does not match sender	Re-sign transaction
`TX_INVALID_NONCE`	Invalid nonce	Nonce mismatch	Get current nonce
`TX_INVALID_GAS_LIMIT`	Invalid gas limit	Below intrinsic gas	Increase gas limit
`TX_INVALID_GAS_PRICE`	Invalid gas price	Below minimum	Increase gas price
`TX_INVALID_VALUE`	Invalid value	Negative or overflow	Check amount
`TX_INVALID_DATA`	Invalid data	Malformed calldata	Check encoding
`TX_INVALID_TO`	Invalid recipient	Malformed address	Validate address
`TX_TOO_LARGE`	Transaction too large	Exceeds size limit	Reduce data

Execution Errors¶

Code	Name	Description	Resolution
`EXEC_REVERT`	Execution reverted	Contract reverted	Check revert reason
`EXEC_OUT_OF_GAS`	Out of gas	Gas limit exhausted	Increase gas limit
`EXEC_STACK_OVERFLOW`	Stack overflow	Call stack too deep	Reduce call depth
`EXEC_INVALID_JUMP`	Invalid jump	Invalid EVM jump	Fix contract code
`EXEC_INVALID_OPCODE`	Invalid opcode	Unknown instruction	Fix contract code
`EXEC_WRITE_PROTECTION`	Write protection	Static call modified state	Use non-static call

Revert Reasons¶

When a contract reverts, the reason is included in the error:

{
  "code": -32006,
  "message": "Execution reverted",
  "data": {
    "reason": "ERC20: insufficient balance",
    "data": "0x08c379a0..."
  }
}

Common revert reasons:

Reason	Description
`ERC20: insufficient balance`	Token balance too low
`ERC20: insufficient allowance`	Approval amount too low
`Ownable: caller is not owner`	Not contract owner
`Pausable: paused`	Contract is paused
`ReentrancyGuard: reentrant call`	Reentrancy detected

SDK Errors¶

TypeScript SDK¶

import {
  AcdcError,
  RpcError,
  NetworkError,
  InvalidAddressError,
  InsufficientFundsError,
  NonceError,
  SignatureError,
  TimeoutError
} from '@acdc/sdk';

try {
  await client.sendTransaction(tx);
} catch (error) {
  if (error instanceof InsufficientFundsError) {
    console.log('Need more ACDC');
    console.log('Required:', error.required);
    console.log('Available:', error.available);
  } else if (error instanceof NonceError) {
    console.log('Nonce issue:', error.message);
    console.log('Expected:', error.expected);
    console.log('Got:', error.got);
  } else if (error instanceof RpcError) {
    console.log('RPC Error:', error.code, error.message);
  } else if (error instanceof NetworkError) {
    console.log('Network Error:', error.message);
  }
}

Error Class	Code	Description
`RpcError`	varies	JSON-RPC error from node
`NetworkError`	`NETWORK_ERROR`	Connection failed
`TimeoutError`	`TIMEOUT`	Request timed out
`InvalidAddressError`	`INVALID_ADDRESS`	Address format invalid
`InsufficientFundsError`	`INSUFFICIENT_FUNDS`	Balance too low
`NonceError`	`NONCE_ERROR`	Nonce mismatch
`SignatureError`	`SIGNATURE_ERROR`	Signing failed
`ContractError`	`CONTRACT_ERROR`	Contract call failed

Rust SDK¶

use acdc_sdk::{AcdcError, RpcError};

match client.send_transaction(tx).await {
    Ok(receipt) => println!("Success: {:?}", receipt),
    Err(AcdcError::Rpc(RpcError { code, message, .. })) => {
        eprintln!("RPC error {}: {}", code, message);
    }
    Err(AcdcError::InsufficientFunds { required, available }) => {
        eprintln!("Need {} but have {}", required, available);
    }
    Err(AcdcError::Network(e)) => {
        eprintln!("Network error: {}", e);
    }
    Err(e) => eprintln!("Error: {}", e),
}

Error Variant	Description
`AcdcError::Rpc`	JSON-RPC error
`AcdcError::Network`	Connection error
`AcdcError::Timeout`	Request timeout
`AcdcError::InvalidAddress`	Address invalid
`AcdcError::InsufficientFunds`	Balance too low
`AcdcError::Signature`	Signing error
`AcdcError::Abi`	ABI encode/decode error

CLI Errors¶

Exit Code	Name	Description
0	Success	Command completed
1	General error	Unspecified error
2	Invalid arguments	Bad command line args
3	Network error	Connection failed
4	Transaction error	Transaction failed
5	Wallet error	Wallet operation failed
6	Contract error	Contract interaction failed
7	Configuration error	Bad config file

CLI Error Messages¶

# Insufficient funds
acdc send --to dx1... --amount 1000000
# Error: Insufficient funds
# Required: 1000000 ACDC
# Available: 100 ACDC
# Exit code: 4

# Invalid address
acdc send --to invalid_address --amount 1
# Error: Invalid address format
# Provided: invalid_address
# Expected: dx1... or ax1...
# Exit code: 2

# Network error
acdc query balance --network mainnet
# Error: Failed to connect to RPC endpoint
# URL: https://delta-rpc.ac-dc.network
# Reason: Connection refused
# Exit code: 3

Alpha Chain Errors¶

Record Errors¶

Code	Name	Description
`RECORD_NOT_FOUND`	Record not found	Record does not exist
`RECORD_SPENT`	Record spent	Record already consumed
`RECORD_INVALID`	Invalid record	Record structure invalid
`RECORD_MISMATCH`	Record mismatch	Record does not match proof

Proof Errors¶

Code	Name	Description
`PROOF_INVALID`	Invalid proof	ZK proof verification failed
`PROOF_EXPIRED`	Proof expired	Proof timestamp too old
`PROOF_MALFORMED`	Malformed proof	Proof structure invalid

View Key Errors¶

Code	Name	Description
`VIEW_KEY_INVALID`	Invalid view key	View key format wrong
`VIEW_KEY_MISMATCH`	View key mismatch	View key does not match address
`DECRYPT_FAILED`	Decryption failed	Could not decrypt record

Staking Errors¶

Code	Name	Description
`STAKE_INSUFFICIENT`	Insufficient stake	Stake amount below minimum
`STAKE_LOCKED`	Stake locked	Stake in unbonding period
`VALIDATOR_NOT_FOUND`	Validator not found	Unknown validator address
`VALIDATOR_INACTIVE`	Validator inactive	Validator not accepting delegates
`VALIDATOR_JAILED`	Validator jailed	Validator is slashed/jailed
`REWARDS_NONE`	No rewards	No rewards to claim
`UNBONDING_EXISTS`	Unbonding in progress	Already unbonding

Governance Errors¶

Code	Name	Description
`PROPOSAL_NOT_FOUND`	Proposal not found	Unknown proposal ID
`PROPOSAL_NOT_ACTIVE`	Proposal not active	Voting period ended
`PROPOSAL_THRESHOLD`	Below threshold	Not enough stake to propose
`ALREADY_VOTED`	Already voted	Cannot vote twice
`NO_VOTING_POWER`	No voting power	No staked tokens
`INVALID_VOTE`	Invalid vote	Vote must be yes/no/abstain

Bridge Errors¶

Code	Name	Description
`BRIDGE_PAUSED`	Bridge paused	Bridge temporarily disabled
`BRIDGE_LIMIT`	Bridge limit	Daily/transaction limit exceeded
`BRIDGE_PROOF_INVALID`	Invalid proof	Bridge proof failed
`BRIDGE_ALREADY_CLAIMED`	Already claimed	Tokens already claimed
`BRIDGE_NOT_FINALIZED`	Not finalized	Cross-chain tx not finalized

HTTP Status Codes¶

REST API responses:

Status	Description
200	Success
400	Bad request / Invalid parameters
401	Unauthorized / Invalid API key
403	Forbidden / Rate limited
404	Not found
429	Too many requests
500	Internal server error
502	Bad gateway
503	Service unavailable

WebSocket Close Codes¶

Code	Description
1000	Normal closure
1001	Going away
1002	Protocol error
1003	Unsupported data
1006	Abnormal closure
1008	Policy violation
1009	Message too big
1011	Unexpected condition
4000	Rate limited
4001	Invalid subscription
4002	Subscription limit
4003	Authentication failed

Debugging Errors¶

Enable Debug Logging¶

TypeScript:

const client = new AcdcClient({
  chain: 'delta',
  network: 'mainnet',
  logLevel: 'debug'
});

Rust:

std::env::set_var("RUST_LOG", "acdc_sdk=debug");
let client = AcdcClient::new(Network::DeltaMainnet)?;

CLI:

ACDC_LOG=debug acdc send --to dx1... --amount 1

Get Detailed Error Info¶

try {
  const tx = await signer.sendTransaction(request);
} catch (error) {
  if (error.code === 'CALL_EXCEPTION') {
    // Get revert reason
    const reason = await client.call(request).catch(e => e.reason);
    console.log('Revert reason:', reason);

    // Simulate to get trace
    const trace = await client.debug.traceCall(request);
    console.log('Trace:', trace);
  }
}