Common Error Codes
ERC-4337 Error Codes
| Error Code | Description | Solution |
|---|---|---|
| AA10 | Sender already constructed | Account already deployed, use existing address |
| AA13 | InitCode failed | Check your account factory and initialization parameters |
| AA21 | Signature validation failed | Verify signature format and signer key |
| AA22 | Timestamp expired | Transaction took too long, retry with fresh signature |
| AA23 | Paymaster timestamp expired | Paymaster approval expired, request new approval |
| AA24 | Signature error | Invalid signature format or wrong chain ID |
| AA25 | Invalid nonce | Account nonce mismatch - may not be deployed |
| AA31 | Paymaster deposit too low | Check your Gas Tank balance |
| AA33 | Paymaster validation failed | Verify paymaster configuration and Gas Tank balance |
| AA40 | Over verification gas limit | Reduce complexity of your operation |
| AA41 | Over execution gas limit | Split into smaller batches |
Common Issues
1. UserOperation Execution Reverted
Symptoms:- Error message contains “execution reverted”
- Transaction fails after submission
- Invalid calldata encoding
- Target contract reverted
- Insufficient token balance for the operation
2. Paymaster Validation Failed
Symptoms:- Error contains “paymaster” or “AA31/AA33”
- Sponsored transactions fail
- Gas Tank has insufficient balance
- API key is invalid or doesn’t include the network
- Paymaster is not configured for the network
- Check your Gas Tank balance in the Gelato App
- Verify your API key includes the target network
- Ensure you’re using the correct API key for sponsored payments
3. Insufficient Funds for Gas
Symptoms:- Error contains “insufficient funds”
- Native or ERC-20 payment fails
- User doesn’t have enough native tokens
- User doesn’t have enough ERC-20 tokens for gas payment
- Account is not deployed yet
4. Account Not Deployed
Symptoms:- Error contains “AA25” or nonce-related errors
- First transaction fails
- Smart account hasn’t been deployed yet
- Using wrong account address
5. Invalid Signature
Symptoms:- Error contains “AA21” or “AA24”
- Signature validation fails
- Wrong private key
- Wrong chain ID
- Signature expired
6. Transaction Pending Forever
Symptoms:- Transaction submitted but never confirms
wait()never resolves
- Network congestion
- Bundler mempool issues
- Low gas price
Debugging Tips
1. Enable Verbose Logging
2. Use Gas Estimation
3. Check Network Support
Before deploying, verify your network is supported:4. Verify API Key Configuration
- Go to Gelato App
- Navigate to Paymaster & Bundler > API Keys
- Verify the API key includes your target network
- Check the API key type (sponsor vs. non-sponsor)
Getting Help
If you’re still experiencing issues:- Check the Gelato Discord for community support
- Review the API Endpoints documentation
- Report issues on GitHub
Additional Resources
- Create an API Key - Setup guide
- Gas Tank Setup - Fund your Gas Tank
- Estimate Gas - Gas estimation guide