> ## Documentation Index
> Fetch the complete documentation index at: https://developers.circle.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Transaction states and errors
> Reference for the states, error reasons, and error details surfaced on Circle Wallets transaction and challenge webhooks and API responses.
## 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](/wallets/transaction-limits-and-optimizations#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
```mermaid theme={null}
stateDiagram-v2
[*] --> INITIATED
INITIATED --> QUEUED
QUEUED --> CLEARED
CLEARED --> SENT
SENT --> CONFIRMED
CONFIRMED --> COMPLETE
SENT --> COMPLETE : instant finality
SENT --> STUCK
STUCK --> SENT : accelerate
INITIATED --> CANCELLED
QUEUED --> CANCELLED
SENT --> CANCELLED
SENT --> FAILED
STUCK --> FAILED
CLEARED --> DENIED
```
## 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](/api-reference/wallets/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
```mermaid theme={null}
stateDiagram-v2
[*] --> PENDING
PENDING --> IN_PROGRESS : user approves
IN_PROGRESS --> COMPLETED
IN_PROGRESS --> FAILED
PENDING --> EXPIRED
```
## 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](/api-reference/wallets/error-codes).
| errorReason | Description |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ESTIMATION_ERROR` | Transaction estimation failed during node execution. See [Estimation error details](#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](/wallets/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](/wallets/gas-station/policy-management) configuration. |
| `SOLANA_ATA_NOT_FOUND` | The recipient's Associated Token Account (ATA) on Solana does not exist. See [Solana ATA sponsorship](/wallets/gas-station/solana-ata-sponsorship) to have Gas Station fund ATA creation, or [create and fund the ATA](/wallets/gas-station/create-solana-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](https://tenderly.co/) to step
through execution and identify where and why it reverts.