Transaction Issues

Last updated: February 2, 2026

Here's how to troubleshoot transactions in HIFI:

Common Transaction Errors (40xxxx)

CodeErrorSolution

400001

INVALID_TRANSACTION_ROUTE

Check currency/crypto/rail combination is supported

400002

INVALID_ACCOUNT_FOR_TRANSACTION

Verify bank account is valid for this transaction type

400003

TRANSACTION_REQUEST_ALREADY_EXISTS

Use a different requestId

400005

QUOTE_NOT_READY

Wait and retry - quote is still being generated

400006

INVALID_QUOTE

Quote expired - request a new one

400301

TRANSACTION_NOT_FOUND

Verify transaction ID exists

400401

INSUFFICIENT_BALANCE

Check wallet balance before transfer

400402

INSUFFICIENT_CREDIT_BALANCE

Top up credit balance for fees

Wallet Management Errors

CodeErrorDescription

600001

INVALID_WALLET_CONFIG

Invalid wallet configuration provided

600001

WALLET_ALREADY_EXISTS

Wallet already exists for this configuration

600301

WALLET_NOT_FOUND

Wallet not found for the user

600501

INACTIVE_WALLET

Wallet is not active

Best Practices

  1. Always check error codes before displaying generic messages

  2. Implement retry logic for 5xx errors

  3. Verify balances before initiating transfers

  4. Validate currency pairs are supported before transactions

For real-time status updates, subscribe to webhook events like ONRAMP.STATUS.* and OFFRAMP.STATUS.*.

Pending or Stuck Transactions

Transactions can be in a PENDING state while awaiting blockchain confirmation. For different transaction types:

  • Wallet transfers: Progress through CREATED → INITIATED → PENDING → COMPLETED

  • Batch transfers: Same progression, with atomic execution (all succeed or fail together)

  • Bridging: Has multiple phases - SOURCE_PENDING and DESTINATION_PENDING while awaiting chain confirmations

  • Offramps: CRYPTO_PENDING (awaiting blockchain confirmation) and FIAT_PENDING (awaiting settlement)

Transfer approvals can also cause transactions to appear "stuck" in PENDING_APPROVAL status until an admin approves or rejects them. These expire after 1 week for on-chain transfers or 1 day for offramps.

Refunds and Reversals

  • CRYPTO_RETURNED: For offramps, if a transaction fails, funds are refunded to the user's wallet with status CRYPTO_RETURNED

  • Batch transfers: Use atomic execution—if any transfer fails, the entire batch fails and no funds are moved

  • Rejected transfers: When a pending approval is rejected, the transfer is cancelled and funds return to the sender

For failed transactions, check the failedReason field for specific error details.