Guides

Understanding Transaction Status

BitPowr transaction processing involves multiple stages from creation to final confirmation on the blockchain. This guide explains all transaction statuses and sub-statuses to help you monitor and handle transactions effectively.

Transaction Status Flow

TRANSACTION.NEW
    ↓
TRANSACTION.PENDING
    ↓
TRANSACTION.PROCESSING
    ↓
TRANSACTION.QUEUE (if needed)
    ↓
TRANSACTION.PRE_BROADCAST
    ↓
TRANSACTION.BROADCASTED
    ↓
TRANSACTION.AWAITING_CONFIRMATION
    ↓
TRANSACTION.CONFIRMED (Success)

OR

TRANSACTION.STUCK → TRANSACTION.DROPPED
TRANSACTION.FAILED
TRANSACTION.CANCELLED

Transaction Statuses

1. TRANSACTION.NEW

Description: Transaction has been newly created and accepted by the BitPowr system.

What it means:

  • Transaction request has been validated
  • Transaction record created in BitPowr database
  • Initial processing has begun

Next steps: Will automatically move to PENDING status

2. TRANSACTION.PENDING

Description: Transaction is prepared and ready for processing.

What it means:

  • Transaction parameters have been validated
  • Wallet balances have been checked
  • Transaction is queued for processing

Next steps: Will move to PROCESSING when picked up by transaction relayer

3. TRANSACTION.PROCESSING

Description: Transaction processing has started on the transaction relayer.

What it means:

  • Transaction relayer is actively working on the transaction
  • Blockchain-specific preparations are being made
  • UTXO selection, gas estimation, or fee calculation in progress

Next steps: Will move to QUEUE (if needed) or PRE_BROADCAST

4. TRANSACTION.QUEUE

Description: Transaction is queued due to pending transactions that need to be processed first.

What it means:

  • There are earlier transactions from the same wallet that must complete first
  • Prevents nonce conflicts and ensures proper transaction ordering
  • Common for wallets with high transaction volumes

Next steps: Will move to PRE_BROADCAST when previous transactions clear

5. TRANSACTION.PRE_BROADCAST

Description: Transaction is about to be broadcast to the blockchain network.

What it means:

  • Final transaction preparation is complete
  • Transaction is signed and ready for network submission
  • About to be sent to blockchain nodes

Next steps: Will move to BROADCASTED immediately

6. TRANSACTION.BROADCASTED

Description: Transaction has been successfully broadcast to the blockchain network.

What it means:

  • Transaction has been sent to blockchain nodes
  • Network has received the transaction
  • Transaction is now in the blockchain's mempool

Next steps: Will move to AWAITING_CONFIRMATION

7. TRANSACTION.AWAITING_CONFIRMATION

Description: Transaction is broadcast and waiting for blockchain confirmation.

What it means:

  • Transaction is in the blockchain's mempool
  • Miners/validators are processing the transaction
  • Waiting for inclusion in a confirmed block

Next steps: Will move to CONFIRMED when included in a block

8. TRANSACTION.STUCK

Description: Transaction has spent too much time in processing without progress.

What it means:

  • Transaction may have network issues
  • Fees might be too low for current network conditions
  • Blockchain congestion may be affecting processing

Next steps: May be retried or will move to DROPPED

9. TRANSACTION.DROPPED

Description: Transaction was dropped after spending too much time processing.

What it means:

  • Transaction exceeded maximum processing time limits
  • Network conditions prevented successful completion
  • Transaction will not be completed

Next steps: Transaction is final - may need to create a new transaction

10. TRANSACTION.FAILED / TRANSACTION.FAIL

Description: Transaction failed during processing or on the blockchain.

What it means:

  • An error occurred that prevented transaction completion
  • Could be due to insufficient funds, network issues, or blockchain rejection
  • Check sub-status for specific failure reason

Next steps: Transaction is final - review error and create new transaction if needed

11. TRANSACTION.CANCELLED

Description: Transaction was cancelled before completion.

What it means:

  • Transaction was manually cancelled by user or system
  • Processing was stopped before blockchain broadcast
  • No blockchain fees were consumed

Next steps: Transaction is final - create new transaction if needed

Transaction Sub-Statuses

Sub-statuses provide additional detail about why a transaction failed or encountered issues.

1. TRANSACTION.ERROR

Description: A general error occurred during transaction processing.

Common causes:

  • System errors during processing
  • Unexpected technical issues
  • Network connectivity problems

Resolution: Review transaction details and retry if appropriate

2. TRANSACTION.FAILED_ONCHAIN

Description: Transaction failed after being broadcast to the blockchain.

Common causes:

  • Smart contract execution failed
  • Gas limit too low for EVM transactions
  • Invalid transaction parameters

Resolution: Check blockchain explorer for failure details, adjust parameters and retry

3. TRANSACTION.INSUFFICIENT_AMOUNT / TRANSACTION.INSUFFICIENT_FUND

Description: Insufficient balance to complete the transaction.

Common causes:

  • Wallet balance is lower than transaction amount
  • Tokens have been spent in other transactions
  • Balance calculation error

Resolution: Check wallet balance and reduce transaction amount or add funds

4. TRANSACTION.INSUFFICIENT_FEE

Description: Insufficient balance to pay transaction fees.

Common causes:

  • Not enough ETH for gas fees on Ethereum
  • Insufficient SOL for fees on Solana
  • Not enough BTC for mining fees

Resolution: Add native tokens for fees or reduce transaction amount

5. TRANSACTION.CAN_NOT_BROADCAST

Description: Transaction could not be broadcast to the blockchain network.

Common causes:

  • Network connectivity issues
  • Invalid transaction format
  • Blockchain node rejection

Resolution: Check network status and retry, or contact support

6. TRANSACTION.CANCELLED

Description: Transaction was cancelled (same as primary status).

Common causes:

  • Manual cancellation by user
  • System cancellation due to timeout
  • Automated cancellation due to conditions

Resolution: Create new transaction if still needed

7. TRANSACTION.FAIL / TRANSACTION.FAIL

Description: General transaction failure (same as primary status).

Common causes:

  • Various failure conditions
  • Check other sub-statuses for specifics
  • System or network errors

Resolution: Review failure details and retry with corrected parameters


Approval Related Status

TRANSACTION.PENDING_APPROVAL

Description: Transaction requires manual approval before processing can continue.
What it means:

  • Transaction requires approval from authorized personnel
  • Common for high-value transactions or sensitive operation
  • Compliance or security policies require manual reviewTransaction is on hold pending approval decision

Next steps: Will move to APPROVED or REJECTED based on approval decision

TRANSACTION.APPROVED

Description: Transaction has been approved and can proceed with processing.

What it means:

  • Manual approval has been granted by authorized personnel
  • Transaction has passed compliance and security checks
  • Processing will resume automatically
  • Transaction will continue to PENDING status

Next steps: Will move to PENDING for continued processing

TRANSACTION.REJECTED

Description: Transaction has been rejected during the approval process.

What it means:

  • Manual approval was denied by authorized personnel
  • Transaction failed compliance or security review
  • Transaction will not be processed further
  • Rejection reason should be available in transaction details

Next steps: Transaction is final - review rejection reason and create new transaction if appropriate

Status Monitoring Best Practices

1. Polling Strategy

// Example polling implementation
const checkTransactionStatus = async (transactionId) => {
  const response = await fetch(`/api/v1/transactions/${transactionId}`, {
    headers: { 'Authorization': 'Bearer <token>' }
  });
  const transaction = await response.json();
  return transaction.status;
};

// Poll every 5 seconds for non-final statuses
const finalStatuses = [
  'TRANSACTION.CONFIRMED',
  'TRANSACTION.FAILED',
  'TRANSACTION.DROPPED',
  'TRANSACTION.CANCELLED'
];

2. Error Handling

const handleTransactionStatus = (status, subStatus) => {
  switch (status) {
    case 'TRANSACTION.FAILED':
      if (subStatus === 'TRANSACTION.INSUFFICIENT_FEE') {
        // Prompt user to add funds for fees
      } else if (subStatus === 'TRANSACTION.INSUFFICIENT_FUND') {
        // Prompt user to add funds or reduce amount
      }
      break;
    case 'TRANSACTION.STUCK':
      // Consider showing speed up options for Bitcoin RBF
      break;
    case 'TRANSACTION.DROPPED':
      // Offer to retry the transaction
      break;
  }
};

Status Timelines by Blockchain

Ethereum/EVM Chains

  • NEW → BROADCASTED: 1-30 seconds
  • AWAITING_CONFIRMATION: 15 seconds - 10+ minutes (depends on gas price)
  • Total time: 30 seconds - 15 minutes

Bitcoin

  • NEW → BROADCASTED: 1-60 seconds
  • AWAITING_CONFIRMATION: 10 minutes - 6+ hours (depends on fee rate)
  • Total time: 10 minutes - 6+ hours

Solana

  • NEW → BROADCASTED: 1-10 seconds
  • AWAITING_CONFIRMATION: 1-30 seconds
  • Total time: 2-40 seconds

TRON

  • NEW → BROADCASTED: 1-15 seconds
  • AWAITING_CONFIRMATION: 1-3 minutes
  • Total time: 1-5 minutes

Troubleshooting Common Status Issues

Transaction Stuck in PROCESSING

Possible causes:

  • High network congestion
  • Wallet has many pending transactions
  • System processing delays

Solutions:

  • Wait for natural progression
  • Check for earlier pending transactions
  • Contact support if stuck for >30 minutes

Transaction Stuck in AWAITING_CONFIRMATION

Possible causes:

  • Low fees (Bitcoin/Ethereum)
  • Network congestion
  • Blockchain issues

Solutions:

  • For Bitcoin: Use RBF to increase fees
  • For Ethereum: Wait or use transaction acceleration services
  • Monitor blockchain network status

Frequent INSUFFICIENT_FEE Errors

Solutions:

  • Use fee estimation endpoints before transactions
  • Maintain adequate native token balances
  • Monitor network congestion for fee planning
  • Use gas station to ensure you have enough fees

This comprehensive status guide helps developers understand the complete transaction lifecycle and implement robust transaction monitoring in their applications.

Updated about 1 year ago

Did this page help you?