Solana fee sponsorship errors

This page documents errors you may encounter when using Solana fee 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

POLICY_NOT_FOUND

{
  "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
Ensure the policy hasn't been deleted

POLICY_NOT_ACTIVE

{
  "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
Use a different active policy

POLICY_NOT_AUTHORIZED

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

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

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

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

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

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

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

{
  "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
Top up your sponsorship balance
Devnet transactions typically use minimal fees

FEE_LIMIT_EXCEEDED

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

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

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

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

{
  "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 for service disruptions
Retry after a brief delay
Contact support if the issue persists

CLUSTER_NOT_SUPPORTED

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

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

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

Solana-specific errors

ACCOUNT_NOT_FOUND

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

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

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

Debugging tips

Check simulation logs: The data field often contains simulation logs that explain why a transaction failed.
Verify cluster consistency: Ensure your transaction, policy, and endpoint all target the same cluster.
Test on devnet first: Debug issues on devnet before deploying to mainnet-beta.
Monitor your dashboard: The Openfort Dashboard shows sponsorship activity and can help identify patterns in failures.
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 for service disruptions
Review the Solana Integration for working examples
Contact support through the Dashboard