# 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

```json
{
  "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](https://dashboard.openfort.io)
* Ensure the policy hasn't been deleted

### POLICY\_NOT\_ACTIVE

```json
{
  "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](https://dashboard.openfort.io)
* Use a different active policy

### POLICY\_NOT\_AUTHORIZED

```json
{
  "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

```json
{
  "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

```json
{
  "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

```json
{
  "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

```json
{
  "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](/docs/products/infrastructure#supported-entrypoints)

### UNSUPPORTED\_ENTRY\_POINT

```json
{
  "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](/docs/products/infrastructure#supported-entrypoints)

### INVALID\_CHAIN\_ID

```json
{
  "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](/docs/configuration/chains) documentation
* Use a supported chain ID in your request URL

### CHAIN\_ID\_MISMATCH

```json
{
  "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

```json
{
  "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](https://dashboard.openfort.io)
* Top up your sponsorship balance
* Testnet operations are typically free to sponsor

### GAS\_LIMIT\_EXCEEDED

```json
{
  "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

```json
{
  "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

```json
{
  "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

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

The paymaster service is temporarily unavailable.

**Solutions:**

* Check the [Openfort Status Page](https://status.openfort.io) for service disruptions
* Retry after a brief delay
* Contact support if the issue persists

### PAYMASTER\_NOT\_SUPPORTED

```json
{
  "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

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

An unexpected internal error occurred.

**Solutions:**

* Retry the request
* Check the [Status Page](https://status.openfort.io) 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](/docs/configuration/chains)
* 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

1. **Check the full error response**: The `data` field often contains additional context like specific field names or values that caused the error.

2. **Verify your request format**: Use the examples in the [Endpoints](/docs/products/infrastructure/paymaster/ethereum/endpoints) documentation as reference.

3. **Test on testnets first**: Debug issues on testnet before deploying to mainnet.

4. **Monitor your dashboard**: The Openfort Dashboard shows sponsorship activity and can help identify patterns in failures.

5. **Validate locally**: Simulate your UserOperation before submitting to catch issues early.

## Getting Help

If you continue to experience issues:

* Check the [Openfort Status Page](https://status.openfort.io) for service disruptions
* Review the [FAQ](/docs/overview) for common questions
* Contact support through the [Dashboard](https://dashboard.openfort.io)