Transaction states and errors

Transaction states

State	Description
`INITIATED`	The transaction has been initiated.
`QUEUED`	The transaction is in the processing queue.
`CLEARED`	The transaction has passed initial checks and risk screening.
`SENT`	The transaction has been identified in the mempool and assigned a transaction hash.
`STUCK`	The transaction has been sent to the blockchain but could not be included in a block. See Resolve stuck transactions.
`CONFIRMED`	The transaction has been identified on a mined block.
`COMPLETE`	Terminal state. The transaction has successfully completed.
`CANCELLED`	Terminal state. The transaction has been canceled. Re-initiate to retry.
`FAILED`	Terminal state. The transaction has failed. Check `errorReason` and `errorDetails` for the cause. Re-initiate to retry.
`DENIED`	Terminal state. The platform denies the transaction. Check `errorReason` and `errorDetails` for the cause.

You can cancel a transaction in INITIATED, QUEUED, or SENT. You can accelerate a transaction in SENT or STUCK.

CONFIRMED may be omitted or arrive out of order. Instant-finality blockchains such as Arc skip it entirely (SENT → COMPLETE); on other blockchains, webhook delivery isn’t ordered, so CONFIRMED may arrive after COMPLETE or not at all. Treat both as inclusion signals.

Transaction lifecycle

Challenge states

Challenges are the user approval flow for user-controlled wallets. A challenge in FAILED has errorCode and errorMessage fields describing the failure. See Wallets API error codes for the errorCode values.

Status	Description
`PENDING`	The request has been created but not yet approved by the user.
`IN_PROGRESS`	The user has approved the request and it is being executed.
`COMPLETED`	The request is complete.
`FAILED`	The request failed to execute. Re-initiate to retry.
`EXPIRED`	The request expired. Re-initiate to retry.

Challenge lifecycle

Transaction errors

When a transaction enters FAILED, errorReason categorizes the cause and errorDetails (when present) provides the specific message. For the numeric error codes returned in API responses, see Wallets API error codes.

errorReason	Description
`ESTIMATION_ERROR`	Transaction estimation failed during node execution. See Estimation error details for common causes and remedies.
`INSUFFICIENT_NATIVE_TOKEN`	The wallet doesn’t have enough of the blockchain’s native asset to cover gas fees for all pending transactions.
`ABI_SIGNATURE_PARAMS_MISMATCH`	The ABI signature and parameters don’t match.
`FEE_EXCEEDS_MAX_ALLOWANCE`	The fee exceeds the per-transaction native token limit that protects against unintended sends.
`QUERY_NFT_METADATA_ERROR`	The NFT metadata cannot be found.
`GAS_LIMIT_TOO_LOW`	The provided `gasLimit` was too low to complete the transaction.
`TRANSACTION_UNDER_PRICE`	The transaction’s `maxFee` or `priorityFee` is below the current mempool floor when the mempool is full.
`FAILED_ON_CHAIN`	The blockchain failed to process the transaction.
`FAILED_REORG`	The transaction was dropped because of a blockchain reorg.
`INTERNAL_ERROR`	The transaction failed due to an internal error.
`PAYMASTER_POLICY_NOT_ACTIVATED`	The Gas Station policy hasn’t been set or activated.
`PAYMASTER_POLICY_EXCEED_MAX_DAILY_TRANSACTIONS`	The Gas Station policy’s max daily transaction limit has been reached. Retry tomorrow or raise the policy limit.
`PAYMASTER_POLICY_EXCEED_MAX_SPEND_USD_PER_TX`	The transaction exceeds the policy’s per-transaction USD spend limit. Reduce the amount or raise the policy limit.
`PAYMASTER_POLICY_EXCEED_MAX_SPEND_USD_DAILY`	The policy’s max daily USD spend limit has been reached. Retry tomorrow or raise the policy limit.
`PAYMASTER_POLICY_EXCEED_MAX_NATIVE_TOKEN_DAILY`	The policy’s max daily native-token spend limit has been reached. Retry tomorrow or raise the policy limit.
`PAYMASTER_POLICY_SENDER_IN_BLOCKLIST`	The sender wallet is blocked by the Gas Station policy. Update the policy blocklist to unblock the wallet.
`PAYMASTER_ENTITY_RESTRICTION`	Your account is restricted from using Gas Station. Check your Gas Station policy configuration.
`SOLANA_ATA_NOT_FOUND`	The recipient’s Associated Token Account (ATA) on Solana does not exist. See Solana ATA sponsorship to have Gas Station fund ATA creation, or create and fund the ATA yourself.

Estimation error details

When a transaction fails with ESTIMATION_ERROR, errorDetails provides the specific reason.

Insufficient balance

The wallet or contract doesn’t have enough tokens to complete the transaction.

errorDetails	Cause	Remedy
`ERC20: transfer amount exceeds balance`	The wallet doesn’t have enough ERC-20 tokens to complete the transfer.	Verify the wallet has sufficient token balance before initiating the transaction. Top up the wallet if needed.
`ERC1155: insufficient balance for transfer`	The wallet doesn’t have enough ERC-1155 tokens (NFTs or semi-fungible tokens) to transfer.	Check the wallet’s ERC-1155 balance for the specific token ID. Ensure the correct token ID and amount are specified.
`Insufficient Balance`	General insufficient balance error. The wallet either doesn’t have enough gas or doesn’t have enough tokens for the transaction.	Verify the contract has sufficient USDC. This may require the contract owner to top up the contract.

Blocklist and access control

An account is restricted from performing the requested action.

errorDetails	Cause	Remedy
`Blacklistable: account is blacklisted`	The recipient or sender address is on the token contract’s denylist.	Verify you’re not sending to the token contract address itself.
`AccessControl: account ... is missing role ...`	The wallet doesn’t have the role or permission required to execute this function on the contract.	Have the contract administrator grant the necessary role, or use an authorized wallet.

Tokens sent to their own contract address are permanently locked and can’t be recovered. Circle keeps the USDC contract address on its denylist to block this common mistake.

Allowance and approval

Token spending approvals are missing or insufficient.

errorDetails	Cause	Remedy
`ERC20: transfer amount exceeds allowance`	The contract hasn’t been approved to spend enough tokens on behalf of the wallet.	Call the `approve()` function on the token contract to grant sufficient allowance to the spender contract.
`ERC20: insufficient allowance`	The spender doesn’t have enough allowance to transfer the requested amount.	Increase the token allowance by calling `approve()` or `increaseAllowance()`.
`Check allowance` / `Allowance`	Generic allowance error.	Verify and increase token allowance.

Signature and authentication

The cryptographic signature is invalid or expired.

errorDetails	Cause	Remedy
`EIP2612: invalid signature`	The permit signature is invalid, malformed, or was signed by the wrong key.	Generate a new valid signature using the correct private key and parameters.
`Permit: invalid signature`	Invalid permit signature.	Re-sign the permit with correct parameters.
`Invalid signature: not attester`	The signature wasn’t created by an authorized attester (common in CCTP).	Use a signature from an authorized attester.
`Nonce already used`	The nonce in the signed message has already been consumed.	Use a fresh nonce value when creating the signature.

Smart account (ERC-4337)

Account abstraction wallets have specific failure modes.

errorDetails	Cause	Remedy
`AA33 reverted: Pausable: paused`	The smart account or paymaster is paused.	Wait for the contract to be `unpaused`, or contact the administrator.
`AA95 out of gas`	The transaction ran out of gas during execution.	Increase the gas limit for the transaction.

Invalid parameters

Transaction parameters are incorrect.

errorDetails	Cause	Remedy
`Transfer amount must be greater than zero` / `Amount must be nonzero`	The amount parameter cannot be zero.	Provide a positive amount value.
`Amount below minimum` / `USDC amount too small`	The amount is below the minimum required threshold.	Increase the amount to meet minimum requirements.
`ERC20: transfer to the zero address`	Cannot transfer tokens to the zero address (0x0).	Provide a valid non-zero recipient address.
`ERC721: invalid token ID`	The specified NFT token ID doesn’t exist.	Verify the token ID exists and is valid.
`Max fee must be less than amount`	The fee exceeds the transaction amount.	Reduce the fee or increase the transaction amount.
`Slippage Limit Exceeded`	The price slippage exceeds the allowed tolerance.	Increase slippage tolerance or wait for better market conditions.
`Too little received` / `insufficient amountReceived`	The output amount is less than the minimum specified.	Adjust minimum output amount or retry when market conditions are favorable.

Timeout and execution

Generic errors during transaction execution.

errorDetails	Cause	Remedy
`Fails to perform transaction estimation.`	General estimation failure without specific details.	Review contract state and transaction parameters. Often caused by network fee fluctuation; retry later often helps.
`execution aborted (timeout = 10s)`	Estimation took too long and timed out.	An RPC node was likely temporarily unavailable. Retry later often helps.
`execution reverted`	Generic revert without a specific reason from the RPC node.	Review contract state and transaction parameters. Often caused by network fee fluctuation; retry later often helps.

Troubleshooting failed transactions

If the cause of the failure isn’t obvious from errorReason or errorDetails, work through these checks:

Verify contract addresses. Confirm the correct contract on the correct blockchain.
Verify transaction parameters. Recipient addresses are valid and non-zero, token amounts meet minimums, and ABI signatures match the function being called.
Check balances and allowances. The wallet has enough of the token being transferred; for ERC-20 spending, the contract has enough allowance from approve().
Review contract state. The contract isn’t paused, and role-based access requirements are satisfied.
Verify authorization. The calling wallet has the roles required by the contract. Check blocklist status when working with regulated tokens such as USDC.
Retry time-sensitive operations. Regenerate expired signatures or nonces. Retry after a short delay if the error suggests the RPC node was temporarily unavailable.

For complex reverts where errorDetails doesn’t provide enough information, simulate the failing transaction in Tenderly to step through execution and identify where and why it reverts.

API overview

Configurations

Developer-controlled

User-controlled

Modular

Compliance Engine

Transaction states and errors