# Solana gas sponsorship errors

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

## Policy errors

:::info
Solana gas sponsorship policies use **project** scope only. These errors arise when project-scoped policies are evaluated automatically — there is no per-request `policyId` parameter on Solana endpoints.
:::

### POLICY\_NOT\_FOUND

```json
{
  "code": -32602,
  "message": "Policy not found: sp_abc123",
  "data": { "policyId": "sp_abc123" }
}
```

The specified policy ID doesn't exist.

**Solutions:**

* Verify the `policyId` in your request 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: sp_abc123",
  "data": { "policyId": "sp_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: sp_abc123",
  "data": { "policyId": "sp_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\_CLUSTER\_MISMATCH

```json
{
  "code": -32602,
  "message": "Policy cluster (mainnet-beta) does not match requested cluster (devnet)",
  "data": { "policyCluster": "mainnet-beta", "requestedCluster": "devnet" }
}
```

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

**Solutions:**

* Use a policy configured for the target cluster
* Create a new policy for the desired cluster

### POLICY\_VIOLATION

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

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

**Solutions:**

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

***

## Validation errors

### INVALID\_TRANSACTION

```json
{
  "code": -32602,
  "message": "Invalid transaction: malformed base64 encoding",
  "data": { "reason": "malformed base64 encoding" }
}
```

The transaction is malformed or couldn't be deserialized.

**Solutions:**

* Verify the transaction is properly base64-encoded
* Check that the transaction was serialized correctly
* Ensure you're using a compatible version of @solana/web3.js or @solana/kit

### INVALID\_CLUSTER

```json
{
  "code": -32602,
  "message": "Invalid cluster: testnet",
  "data": { "cluster": "testnet" }
}
```

The specified cluster isn't supported.

**Solutions:**

* Use `devnet` or `mainnet-beta` in your endpoint URL
* Check the [supported clusters](#) documentation

### EXPIRED\_BLOCKHASH

```json
{
  "code": -32602,
  "message": "Transaction blockhash has expired",
  "data": { "blockhash": "abc123..." }
}
```

The transaction's recent blockhash is no longer valid.

**Solutions:**

* Get a fresh blockhash before requesting sponsorship
* Submit the sponsored transaction promptly
* Blockhashes expire after approximately 60 seconds

### TRANSACTION\_TOO\_LARGE

```json
{
  "code": -32602,
  "message": "Transaction exceeds maximum size",
  "data": { "size": 1500, "maxSize": 1232 }
}
```

The transaction exceeds Solana's maximum transaction size.

**Solutions:**

* Reduce the number of instructions in the transaction
* Split into multiple transactions
* Optimize instruction data size

***

## Sponsorship errors

### INSUFFICIENT\_FUNDS

```json
{
  "code": -32602,
  "message": "Insufficient sponsorship balance",
  "data": { "available": 1000, "required": 5000 }
}
```

Your sponsorship balance is too low to cover the transaction fees.

**Solutions:**

* Check your balance in the [Openfort Dashboard](https://dashboard.openfort.io)
* Top up your sponsorship balance
* Devnet transactions typically use minimal fees

### FEE\_LIMIT\_EXCEEDED

```json
{
  "code": -32602,
  "message": "Transaction fee exceeds limit: required 50000, limit 10000",
  "data": { "limit": 10000, "required": 50000 }
}
```

The transaction fee exceeds the policy's configured limit.

**Solutions:**

* Increase the fee limit in your policy settings
* Reduce transaction complexity to lower fees
* Split complex operations into multiple transactions

### SPONSORSHIP\_REJECTED

```json
{
  "code": -32602,
  "message": "Sponsorship rejected: simulation failed",
  "data": { "reason": "simulation failed", "logs": ["Program failed..."] }
}
```

The gas sponsorship service rejected the sponsorship request.

**Solutions:**

* Check that the transaction would succeed on its own
* Review the simulation logs in the error data
* Verify all referenced accounts exist and have correct permissions
* Ensure programs are deployed on the target cluster

***

## 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

### FEE\_PAYER\_UNAVAILABLE

```json
{
  "code": -32603,
  "message": "Fee payer unavailable for cluster devnet",
  "data": { "cluster": "devnet" }
}
```

The fee payer 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

### CLUSTER\_NOT\_SUPPORTED

```json
{
  "code": -32602,
  "message": "Cluster not supported: testnet",
  "data": { "cluster": "testnet" }
}
```

The gas sponsorship service isn't available for this cluster.

**Solutions:**

* Use a supported cluster (`devnet` or `mainnet-beta`)
* Contact support if you need additional cluster support

### 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

***

## Solana-specific errors

### ACCOUNT\_NOT\_FOUND

```json
{
  "code": -32602,
  "message": "Account not found: abc123...",
  "data": { "account": "abc123..." }
}
```

A required account doesn't exist on the cluster.

**Solutions:**

* Verify the account address is correct
* Ensure the account is created on the target cluster
* Check that you're using the correct cluster endpoint

### PROGRAM\_NOT\_DEPLOYED

```json
{
  "code": -32602,
  "message": "Program not deployed: xyz789...",
  "data": { "programId": "xyz789..." }
}
```

The program referenced in the transaction isn't deployed on this cluster.

**Solutions:**

* Verify the program ID is correct
* Ensure the program is deployed on the target cluster
* Use the correct cluster for your program

### INSUFFICIENT\_RENT

```json
{
  "code": -32602,
  "message": "Account would fall below rent-exempt minimum",
  "data": { "account": "abc123...", "required": 890880, "current": 500000 }
}
```

The transaction would cause an account to fall below the rent-exempt minimum.

**Solutions:**

* Increase the transfer amount to meet rent requirements
* Ensure accounts maintain minimum balance after transaction
* Consider closing accounts you no longer need

***

## Jito bundle errors

These errors are specific to the [`estimateBundleFee`](/docs/products/infrastructure/paymaster/solana/endpoints#estimatebundlefee) and [`signAndSendBundle`](/docs/products/infrastructure/paymaster/solana/endpoints#signandsendbundle) bundle methods. Bundles are **mainnet-only**.

### Duplicate transactions

```json
{
  "code": -32060,
  "message": "Jito error: Jito API error: duplicate transactions"
}
```

Two transactions in the bundle are byte-identical. Jito rejects bundles with duplicate transactions.

**Solutions:**

* Make each transaction unique — add a per-transaction memo or vary the instructions so no two encode to the same bytes.

### Insufficient bundle payment

```json
{
  "code": -32000,
  "message": "InsufficientBundlePayment"
}
```

The SPL payment in the bundle doesn't cover the Kora fee **plus** the Jito tip.

**Solutions:**

* Remember that [`estimateBundleFee`](/docs/products/infrastructure/paymaster/solana/endpoints#estimatebundlefee) **excludes the tip**. Convert the tip to token units (`fee_in_token / fee_in_lamports × tipLamports`), add it to the estimated fee, and apply a small buffer before setting the payment amount.

### Invalid or expired blockhash

```json
{
  "code": -32093,
  "message": "RPC error: Custom: Invalid blockhash"
}
```

The bundle's blockhash was rejected at simulation time — usually because it was fetched too recently for the simulating node to have seen it yet, or it has since expired.

**Solutions:**

* Fetch the blockhash immediately before building the bundle, and retry with a fresh blockhash on this error (Jito's recommended resend behavior).

### Too many transactions

```json
{
  "code": -32602,
  "message": "A bundle must contain at most 5 transactions"
}
```

A bundle carries 1–5 transactions.

**Solutions:**

* Split the work across multiple bundles, or reduce the transaction count to 5 or fewer.

***

## Debugging tips

1. **Check simulation logs**: The `data` field often contains simulation logs that explain why a transaction failed.

2. **Verify cluster consistency**: Ensure your transaction, policy, and endpoint all target the same cluster.

3. **Test on devnet first**: Debug issues on devnet before deploying to mainnet-beta.

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

5. **Use fresh blockhashes**: Solana blockhashes expire quickly. Always get a fresh blockhash before requesting sponsorship.

## Getting help

If you continue to experience issues:

* Check the [Openfort Status Page](https://status.openfort.io) for service disruptions
* Review [Gasless Solana transactions](/docs/products/embedded-wallet/react/wallet/actions/send-transaction/solana#gasless-solana-transactions) for working examples
* Contact support through the [Dashboard](https://dashboard.openfort.io)