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 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. |
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.
| 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. |
