Paymaster Errors

This page documents errors you may encounter when using the Paymaster. Errors are returned as JSON-RPC error responses with a numeric code, human-readable message, and optional data field with additional context.

Policy Errors

POLICY_NOT_FOUND

{
  "code": -32602,
  "message": "Policy not found: pol_abc123",
  "data": { "policyId": "pol_abc123" }
}

The specified policy ID doesn't exist.

Solutions:

Verify the policyId in your paymasterContext is correct
Check that the policy exists in the Openfort Dashboard
Ensure the policy hasn't been deleted

POLICY_NOT_ACTIVE

{
  "code": -32602,
  "message": "Policy is not active: pol_abc123",
  "data": { "policyId": "pol_abc123" }
}

The policy exists but is disabled.

Solutions:

Enable the policy in the Dashboard
Use a different active policy

POLICY_NOT_AUTHORIZED

{
  "code": -32001,
  "message": "Not authorized to use policy: pol_abc123",
  "data": { "policyId": "pol_abc123" }
}

Your API key doesn't have permission to use this policy.

Solutions:

Verify you're using the correct API key for this project
Check that the policy belongs to your project

POLICY_CHAIN_MISMATCH

{
  "code": -32602,
  "message": "Policy chain (137) does not match requested chain (1)",
  "data": { "policyChainId": 137, "requestedChainId": 1 }
}

The policy is configured for a different chain than the one you are requesting.

Solutions:

Use a policy configured for the target chain
Create a new policy for the desired chain

POLICY_VIOLATION

{
  "code": -32602,
  "message": "Policy violation for 'pol_abc123': spending limit exceeded",
  "data": { "policyId": "pol_abc123", "reason": "spending limit exceeded" }
}

The UserOperation doesn't satisfy the policy's sponsorship rules.

Solutions:

Review your policy rules in the Dashboard
Check common rule violations:
- Contract address not in allowlist
- Spending limit exceeded
- Rate limit reached
- Time-based restrictions

Validation Errors

INVALID_USER_OPERATION

{
  "code": -32602,
  "message": "Invalid UserOperation: missing required field 'sender'",
  "data": { "reason": "missing required field 'sender'" }
}

The UserOperation is malformed or missing required fields.

Solutions:

Verify all required fields are present (sender, nonce, callData, etc.)
Check that hex values are properly 0x-prefixed
Ensure you're using the correct format for your EntryPoint version

INVALID_ENTRY_POINT

{
  "code": -32602,
  "message": "Invalid EntryPoint address: 0xinvalid",
  "data": { "entryPoint": "0xinvalid" }
}

The provided EntryPoint address isn't a valid Ethereum address.

Solutions:

Use a valid checksummed Ethereum address
Use one of the supported EntryPoints

UNSUPPORTED_ENTRY_POINT

{
  "code": -32602,
  "message": "Unsupported EntryPoint: 0x1234...",
  "data": { "entryPoint": "0x1234..." }
}

The EntryPoint address is valid but isn't supported by Openfort.

Solutions:

Use a supported EntryPoint version (v0.6, v0.8, or v0.9)
Check the supported EntryPoints

INVALID_CHAIN_ID

{
  "code": -32602,
  "message": "Unsupported or invalid chain ID: 999",
  "data": { "chainId": 999 }
}

The chain ID in the request URL isn't supported.

Solutions:

Check the Supported Chains documentation
Use a supported chain ID in your request URL

CHAIN_ID_MISMATCH

{
  "code": -32602,
  "message": "Chain ID mismatch: URL specifies 1 but params contain 137",
  "data": { "urlChainId": 1, "paramsChainId": 137 }
}

The chain ID in the URL doesn't match the chain ID in the request parameters.

Solutions:

Ensure the chain ID in your URL matches the chain ID in your params
Use consistent chain IDs throughout your request

Sponsorship Errors

INSUFFICIENT_FUNDS

{
  "code": -32602,
  "message": "Insufficient funds for sponsorship",
  "data": { "available": "1000000", "required": "5000000" }
}

Your sponsorship balance is too low to cover the gas costs.

Solutions:

Check your balance in the Openfort Dashboard
Top up your sponsorship balance
Testnet operations are typically free to sponsor

GAS_LIMIT_EXCEEDED

{
  "code": -32602,
  "message": "Gas limit exceeded: required 5000000, limit 1000000",
  "data": { "limit": "1000000", "required": "5000000" }
}

The UserOperation requires more gas than the policy allows.

Solutions:

Increase the gas limit in your policy settings
Optimize your transaction to use less gas
Split complex operations into multiple transactions

SPONSORSHIP_REJECTED

{
  "code": -32602,
  "message": "Sponsorship rejected: simulation failed",
  "data": { "reason": "simulation failed" }
}

The paymaster rejected the sponsorship request.

Solutions:

Check that the callData would execute successfully
Verify the sender account is properly deployed and configured
Ensure all referenced contracts are deployed on the target chain
Review the detailed error reason for specific issues

Rate Limiting

RATE_LIMITED

{
  "code": -32029,
  "message": "Rate limit exceeded",
  "data": { "retryAfter": 30 }
}

You have exceeded the request rate limit.

Solutions:

Wait for the retryAfter period (in seconds) before retrying
Implement exponential backoff in your application
Consider upgrading your subscription for higher limits

Infrastructure Errors

PAYMASTER_UNAVAILABLE

{
  "code": -32603,
  "message": "Paymaster unavailable for chain 137",
  "data": { "chainId": 137 }
}

The paymaster service is temporarily unavailable.

Solutions:

Check the Openfort Status Page for service disruptions
Retry after a brief delay
Contact support if the issue persists

PAYMASTER_NOT_SUPPORTED

{
  "code": -32602,
  "message": "Paymaster not supported for chain 137 with EntryPoint version 0.6",
  "data": { "chainId": 137, "entryPointVersion": "0.6" }
}

The paymaster isn't available for this chain and EntryPoint version combination.

Solutions:

Check which EntryPoint versions are supported on your chain
Use a different EntryPoint version
Contact support if you need this combination supported

INTERNAL_ERROR

{
  "code": -32603,
  "message": "Internal error: unexpected failure",
  "data": { "reason": "unexpected failure" }
}

An unexpected internal error occurred.

Solutions:

Retry the request
Check the Status Page for known issues
Contact support with the error details if the issue persists

EntryPoint Contract Errors

These errors originate from the EntryPoint contract during on-chain paymaster validation.

AA30: paymaster not deployed

The paymaster contract isn't deployed on this chain.

Solutions:

Verify you're using a supported chain
Contact support if the paymaster should be available

AA31: paymaster deposit too low

The paymaster's deposit in the EntryPoint is insufficient.

Solutions:

This is an infrastructure issue that resolves automatically
Contact support if the error persists

AA32: paymaster expired or not due

The paymaster signature's validity window has passed or hasn't started yet.

Solutions:

Request fresh paymaster data
Submit the UserOperation promptly (within 10 minutes)
Ensure your system clock is synchronized

AA33: paymaster validation reverted

The paymaster's validatePaymasterUserOp function reverted.

Solutions:

Ensure the UserOperation meets sponsorship criteria
Request fresh paymaster data
Check for policy violations

AA34: paymaster signature error

The paymaster signature verification failed.

Solutions:

Request fresh paymaster data
Ensure the paymasterAndData field hasn't been modified after sponsorship

Debugging Tips

Check the full error response: The data field often contains additional context like specific field names or values that caused the error.
Verify your request format: Use the examples in the Endpoints documentation as reference.
Test on testnets first: Debug issues on testnet before deploying to mainnet.
Monitor your dashboard: The Openfort Dashboard shows sponsorship activity and can help identify patterns in failures.
Validate locally: Simulate your UserOperation before submitting to catch issues early.

Getting Help

If you continue to experience issues:

Check the Openfort Status Page for service disruptions
Review the FAQ for common questions
Contact support through the Dashboard