When payments or transactions fail, you'll receive an object containing the failure reason. Depending on when the failure occurs, this information is returned in the synchronous (API) or asynchronous (webhook) response. The following sections outline the reasons that each of these components might fail.
When a payment fails in CPN there are no further actions you can take with that payment ID. You should restart the payment workflow by requesting a new quote and accepting it to create a new payment.
The payment failure notification includes a failure reason (listed below) and a failure code containing more specific information about the failure. The failure code provides information about how to resolve the issue and create a new payment.
| Failure reason | Description |
|---|---|
TRAVEL_RULE_FAILED | The travel rule information included with the payment was rejected |
BANK_VERIFICATION_FAILED | The bank information included with the payment was rejected |
RFI_VERIFICATION_FAILED | The payment failed due to issues related to RFI handling or verification |
EXISTING_RFI_PENDING | An RFI exists on the customer in a non-terminal state |
ONCHAIN_SETTLEMENT_FAILED | The payment couldn't be processed due to an issue with the onchain settlement |
FIAT_SETTLEMENT_FAILED | The payment couldn't be completed due to routing or bank settlement issues |
COMPLIANCE_CHECK_FAILED | The payment was rejected due a compliance check failure |
CANCELLED | The payment is canceled by the originator |
PAYMENT_EXPIRED | The payment is expired and not able to provide further action. |
OTHER | General payment failure not covered by other reasons |
If an onchain transaction fails or becomes stuck, you can create a new transaction or attempt to replace or accelerate the transaction. You may continue to troubleshoot onchain transactions until the payment expires. Note that only one transaction can be associated with a given payment, so you must wait until the current transaction fails or attempt to replace it if you need to update the transaction.
| Failure reason | Description |
|---|---|
CPN_PAYMENT_EXPIRED | The payment corresponding to this transaction is expired. Resolution: Create a new payment and ensure the onchain transaction is completed in its valid time frame. |
SIGNED_TRANSACTION_EXPIRED | (Solana only) The signed transaction is expired. Solana requires you to submit a signed transaction in 150 blocks (~1 min). Resolution: Initiate a new transaction and submit it in the appropriate time frame. |
NONCE_TOO_LOW | The nonce of the signed transaction is lower than the current wallet nonce. Resolution: Submit a new transaction using the latest nonce value for the wallet. |
INSUFFICIENT_GAS_BALANCE | Not enough native tokens were available in the wallet to cover the gas fee for the transaction. Resolution: Fund the wallet with the appropriate amount of native tokens and initiate a new transaction. |
GAS_PRICE_TOO_LOW | The specified gas fee is too low, which may prevent the transaction from being included in a block. Resolution: Create a new transaction with a higher gas fee. |
INSUFFICIENT_TOKEN_BALANCE | The wallet does not have enough USDC in it for the transfer amount. Resolution: Fund the wallet with the appropriate amount of USDC for the payment, then initiate a new transaction. |
OUT_OF_GAS | For EVM chains, the gas limit for the signed transaction is insufficient to cover the execution cost. For Solana, the allocated compute budget falls short of the transaction's requirements, preventing successful execution. Resolution: Create a new transaction with a higher gas limit. |
TX_REPLACEMENT_FAILED | The transaction replacement failed because another transaction with the same nonce (and higher fee) is already the mempool or was mined first. If the replacement fails, the original transaction submitted to the blockchain is still executed. |
SOL_TX_ALREADY_IN_CACHE | (Solana only) The transaction has already been broadcast and is present in the network's cache. Resolution: Wait for the current transaction's confirmation or failure before proceeding. |
TX_ALREADY_CONFIRMED | The transaction was confirmed onchain before the current broadcast attempt. Resolution: If this was unexpected, open a support ticket for further investigation. |
FAILED_ONCHAIN | The transaction failed execution on the blockchain. Resolution: Review the onchain error, correct any issues, and submit a new transaction. |
SOL_BLOCKHASH_EXPIRED | (Solana only) The Solana blockhash assigned to the transaction has expired. Resolution: Initiate a new transaction. |
TRANSACTION_EXPIRED | The transaction is expired and you aren't able to perform any further actions. Resolution: Initiate a new transaction. |
Did this page help you?
© 2023-2025 Circle Technology Services, LLC. All rights reserved.
