Transaction states and errors

API entities, such as transactions and challenges, are processed asynchronously after the initial POST request. As the request is processed, the transaction’s state, or the challenge’s status, will update accordingly. This update can be retrieved either by polling the associated GET endpoint or by subscribing to webhook notifications (recommended).

For more information about managing transactions, see Transaction Rate Limits and Optimizations.

Transaction states

Transactions go through various states after initiation to indicate if they’ve begun processing, are identifiable on the blockchain, complete, failed, or require further action, such as when a transaction becomes STUCK. Specific actions, like canceling or accelerating a transaction, can only be taken when a transaction is in a specific state. Canceling a transaction can only occur when a transaction is in the INITIATED, QUEUED, or SENT states. Accelerating a transaction can only occur when a transaction is in the SENT or STUCK state. If a transaction cannot be successfully completed, it enters the FAILED state and has accompanying errorReason and errorDetails fields that describe the failure. The following table describes the possible states of a transaction:

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 and is ready for further processing.
`SENT`	The transaction has been identified in the Mempool and assigned a transaction hash. The transaction may be accelerated at this stage.
`STUCK`	The transaction has been sent to the blockchain but could not be included in a block. See how to handle stuck transactions to ensure confirmation.
`CONFIRMED`	The transaction has been identified on a mined block. The transaction can no longer be canceled.
`COMPLETE`	Terminal State. The transaction has successfully completed.
`CANCELLED`	Terminal State. The transaction has been canceled and must be re-initiated.
`FAILED`	Terminal State. The transaction has failed. The transaction must be re-initiated.
`DENIED`	Terminal State. The platform denies the transaction. For additional information, refer to the `errorReason` and `errorDetails` fields.

CONFIRMED may be omitted or arrive out of order. On instant finality blockchains such as Arc, Circle Wallets transitions directly from SENT to COMPLETE, skipping CONFIRMED. On other blockchains, webhook delivery order is not guaranteed, so a CONFIRMED notification may arrive after COMPLETE or be omitted entirely. Design your application to treat both CONFIRMED and COMPLETE as signals that a transaction has been included in a block.

Transaction errors

If a transaction cannot be completed and enters the FAILED state, the transaction object has accompanying errorReason and errorDetails fields that describe the failure.

Error Reason	Description
`ESTIMATION_ERROR`	The transaction estimation failed during node execution. See ESTIMATION_ERROR Details for common causes and remedies.
`INSUFFICIENT_NATIVE_TOKEN`	The wallet does not have a sufficient balance of the blockchain’s native asset to cover the gas fees needed for all pending transactions.
`ABI_SIGNATURE_PARAMS_MISMATCH`	The signature and parameter of ABI are mismatched.
`FEE_EXCEEDS_MAX_ALLOWANCE`	The fee exceeds the max allowance. There is one native token fee limit to prevent any unintended transaction from being sent out.
`QUERY_NFT_METADATA_ERROR`	The NFT metadata cannot be found.
`GAS_LIMIT_TOO_LOW`	The provided fee tolerance (`gasLimit`) was too low to complete the requested transaction.
`TRANSACTION_UNDER_PRICE`	The transaction’s max fee or priority fee is lower than the current lowest max fee or priority fee in mempool when mempool is full.
`FAILED_ON_CHAIN`	The transaction failed to be processed by the blockchain.
`FAILED_REORG`	The transaction was dropped because of blockchain re-org.
`INTERNAL_ERROR`	The transaction failed due to an internal error.
`PAYMASTER_POLICY_NOT_ACTIVATED`	The paymaster policy hasn’t been set or activated.
`PAYMASTER_POLICY_EXCEED_MAX_DAILY_TRANSACTIONS`	The maximum number of daily transactions allowed by the paymaster policy has been reached. Try again tomorrow or update the policy limits.
`PAYMASTER_POLICY_EXCEED_MAX_SPEND_USD_PER_TX`	The transaction exceeds the maximum allowable spend in USD as per the paymaster policy for a single transaction. Increase the limits in your policy for such transactions to go through.
`PAYMASTER_POLICY_EXCEED_MAX_SPEND_USD_DAILY`	The maximum daily spending limit in USD set by the paymaster policy has been reached. Try again tomorrow or update the policy limits.
`PAYMASTER_POLICY_EXCEED_MAX_NATIVE_TOKEN_DAILY`	The maximum daily spending limit for native tokens set by the paymaster policy has been reached. Try again tomorrow or update the policy limits.
`PAYMASTER_POLICY_SENDER_IN_BLOCKLIST`	The sender wallet of the transaction is blocked by the paymaster policy. Update the policy blocklist to allow this user to go through.
`PAYMASTER_ENTITY_RESTRICTION`	At this time, your account is restricted from using Gas Station. Go to the Developer Services Console Paymaster page to learn more.
`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.

Challenge states

Challenges go through several statuses to indicate whether they have been presented to the user, completed, and more. If a challenge cannot be successfully completed, it enters the FAILED state and has accompanying errorCode and errorMessage fields that describe the failure.

Status	Description
PENDING	The request has been created but has not yet been 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 has failed to execute. The request must be re-initiated.
EXPIRED	The request has expired. The request must be re-initiated.

ESTIMATION_ERROR details

When a transaction fails with ESTIMATION_ERROR, the errorDetails field provides specific information about why the transaction estimation failed. Below are the common errorDetails values grouped by category, along with their causes and recommended remedies.

Insufficient balance errors

These errors occur when 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 token 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 does not 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 errors

These errors occur when an account is restricted from performing certain actions.

`errorDetails`	Cause	Remedy
`Blacklistable: account is blacklisted`	The recipient or sender address has been added to the token contract’s denylist. See details below.	Verify you’re not sending to the token contract address itself.
`AccessControl: account ... is missing role ...`	The wallet doesn’t have the required role/permission to execute this function on the contract.	Ensure the wallet has been granted the necessary role by the contract administrator, or use an authorized wallet.

Common cause: Sending USDC to the USDC contract addressThe USDC contract address itself is intentionally on Circle’s denylist to prevent developers from accidentally sending USDC tokens to the contract address. Tokens sent to a token contract address would be permanently locked and unrecoverable through normal means.

Allowance and approval errors

These errors occur when 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`	Similar to the preceding error—the spender doesn’t have enough allowance.	Increase the token allowance by calling `approve()` or `increaseAllowance()`.
`Check allowance` / `Allowance`	Generic allowance error.	Verify and increase token allowance.

Signature and authentication errors

These errors occur when cryptographic signatures are 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) errors

These errors occur with smart contract wallets using account abstraction.

`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

These errors occur when 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 errors

These generic errors can occur during transaction execution.

`errorDetails`	Cause	Remedy
`Fails to perform transaction estimation.`	General estimation failure without specific details.	Review contract state and transaction parameters. This often happens due to network fee fluctuation; retry later often helps.
`execution aborted (timeout = 10s)`	The estimation took too long and timed out.	This could be due to an RPC node being temporarily unavailable. Retry later often helps.
`execution reverted`	Generic revert without a specific reason provided by the RPC node.	Review contract state and transaction parameters. This often happens due to network fee fluctuation; retry later often helps.

For guidance on diagnosing and resolving failed transactions, see Troubleshoot failed transactions.

Wallets

Gas fees

Compliance

Contracts

Transaction states and errors

Transaction states

Transaction errors

Challenge states

ESTIMATION_ERROR details

Insufficient balance errors

Blocklist and access control errors

Allowance and approval errors

Signature and authentication errors

Smart account (ERC-4337) errors

Invalid parameters

Timeout and execution errors

​Transaction states

​Transaction errors

​Challenge states

​ESTIMATION_ERROR details

​Insufficient balance errors

​Blocklist and access control errors

​Allowance and approval errors

​Signature and authentication errors

​Smart account (ERC-4337) errors

​Invalid parameters

​Timeout and execution errors

Transaction states

Transaction errors

Challenge states

ESTIMATION_ERROR details

Insufficient balance errors

Blocklist and access control errors

Allowance and approval errors

Signature and authentication errors

Smart account (ERC-4337) errors

Invalid parameters

Timeout and execution errors