Error Handling

Sometimes transactions fail. This guide outlines common failure reasons and provides tools to help you identify the underlying causes.

​

Common Error Types

Transaction errors typically fall into two categories: validation failures and execution failures.

​

Validation Errors

Validation errors occur when the provided transaction data is invalid. These errors commonly relate to invalid data (e.g., signature) during transaction approval. Common issues include:

• Malformed signatures
• Invalid signatures (e.g., from an unauthorized wallet)
• Insufficient signer permissions for transaction approval

An example of a validation error:

"error": {
  "reason": "execution_reverted",
  "message": "Execution reverted, see 'revert' for details",
  "revert": {
    "type": "wallet_authorization",
    "reason": "Invalid signature",
    "reasonData": "AA24",
    "simulationLink": "https://www.tdly.co/shared/simulation/e61be684-5359-48a6-9173-349cd44c6e6c"
  }
}

Troubleshooting steps:

• Verify the transaction signer is valid
• Confirm you’re signing the correct message data
• Verify the signing private key matches the signer wallet

​

Execution Errors

Execution errors occur when a transaction is reverted during runtime. These typically relate to the calls provided during transaction creation. Common causes include:

• Another transaction with the same call was executed already
• State changes between transaction creation and execution (e.g. asset price updated exceeding slippage allowance)

The Crossmint API typically provides specific revert reasons:

"error": {
  "reason": "execution_reverted",
  "message": "Execution reverted, see 'revert' for details",
  "revert": {
    "type": "contract_call",
    "reason": "ERC20: transfer amount exceeds balance",
    "simulationLink": "https://www.tdly.co/shared/simulation/18b810b5-33b6-4091-a3a1-d7318f73bbec"
  }
}

Troubleshooting:

• Review the simulation to understand the revert cause
• Check for similar previous transactions
• Attempt to resubmit with the same parameters

​

Other Errors

If you encounter transaction failures without error details or receive no error message, there may be an issue with the Crossmint infrastructure. First, check our status page to verify API availability and try again later. If the problem continues, please contact our support team.

​

Debugging

The Crossmint API simulates all transactions before submitting them onchain. Failed simulations prevent onchain execution.

In most cases, the transaction will fail during the simulation. If that’s the case, you can use Tenderly to inspect the details. Otherwise, you can use a block explorer to inspect the transaction.

​

Tenderly

Tenderly is an EVM transaction tracing software. For each transaction that is failed during simulation, Crossmint API includes a link to the Tenderly simulation.

​

Block Explorer

If the transaction was included onchain, you can check its status using a block explorer.