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).
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 have 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. |
Transaction Errors
If a transaction cannot be completed and enters the FAILED state, the
transaction object will have 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. Please 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. Please 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. Please 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. Please 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. |
Challenge States
Challenges go through several statuses to indicate if it has been presented to
the user, have been completed, and more.
If a challenge cannot be successfully completed, it will enter the FAILED
state, and have 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 don’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. |
Blacklist 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 blacklisted by the token contract. 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 admin, or use an authorized wallet. |
Common cause: Sending USDC to the USDC contract addressThe USDC contract address itself is intentionally blacklisted by Circle 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 above - 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 RPC node 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 |
General Troubleshooting
If you encounter an errorDetails value not listed above:
- Check the error message carefully - Many errors are self-explanatory
(e.g., “Insufficient balance”, “Not authorized”).
- Verify contract addresses - Ensure you’re interacting with the correct
contract on the correct network.
- Verify transaction parameters - Ensure all addresses, amounts, and other
parameters are correct.
- Check token balances and allowances - Many errors stem from insufficient
balance or missing approvals.
- Review contract state - Some operations are only valid in certain
contract states.
- Verify authorization - Ensure the calling wallet has necessary
permissions.
- Check for blacklisting - Regulated tokens may blacklist certain
addresses.
- Retry - For time-sensitive operations, signatures or nonces may have
expired. Network conditions and RPC node availability may also affect
execution.
Debugging with Tenderly
For complex errors or when the errorDetails doesn’t provide enough
information, Tenderly is a powerful simulating /
debugging tool that can help you understand exactly why a transaction would
fail. 
