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 via subscribing to 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, and more. 

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

If a transaction cannot be successfully completed, it will enter the FAILED state and have an accompanying errorReason detailing the failure. 

The following state diagram shows the flow for transaction states:

The following table describes the possible states of a transaction:

StateDescription
INITIATEDThe transaction has been initiated. 
QUEUEDThe transaction is in the processing queue.
SENTThe transaction has been identified in the Mempool and assigned a transaction hash. The transaction may be accelerated at this stage.
CONFIRMEDThe transaction has been identified on a mined block. The transaction can no longer be canceled. 
COMPLETEDTerminal State. The transaction has successfully completed. 
CANCELEDTerminal State. The transaction has been canceled and must be re-initiated. 
FAILEDTerminal State. The transaction has failed. The transaction must be re-initiated.
DENIEDTerminal State. The platform denies the transaction. For a detailed reason, refer to the errorReason.
ACCELERATEDThe transaction has been accelerated. 

Transaction Errors

If a transaction cannot be completed and enters the FAILED state, the transaction object will have a related errorReason to describe the failure.

errorReasondescription
ESTIMATION_ERRORThe transaction estimation failed during node execution.
INSUFFICIENT_NATIVE_TOKENThe wallet does not have a sufficient balance of the blockchain’s native asset to cover the gas fees needed for all pending transactions.
GAS_LIMIT_TOO_LOWThe provided fee tolerance (gasLimit) was too low to complete the requested transaction.
QUERY_NFT_METADATA_ERRORThe NFT metadata can not be found.
FAILED_ON_ONCHAINThe transaction failed to be processed by the blockchain. Please try again.
FAILED_REORGThe transaction failed dropped due to a [re-org]
INTERNAL_ERRORThe transaction failed due to an internal error
ABI_SIGNATURE_PARAMS_MISMATCHThe signature and parameter of ABI are mismatched.
FEE_EXCEEDS_MAX_ALLOWANCEThe fee exceeds max allowance. There is 1 native token fee limit to prevent any unintended transaction to be sent out.
TRANSACTION_UNDER_PRICEThe transaction's max fee or priority fee is lower than the current lowest max fee or priority fee in mempool when mempool is full.

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 an accompanying errorCode and errorMessage detailing the failure.

StatusDescription
PENDINGThe request has been created but has not yet been approved by the user.
IN_PROGRESSThe user has approved the request, and it is being executed.
COMPLETEDThe request is complete.
FAILEDThe request has failed to execute. The request must be re-initiated.
EXPIREDThe request has expired. The request must be re-initiated.