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 20 days ago