How to diagnose Gas Manager errors?

Below are common errors related to Gas Manager.

Policy ID Errors

Example error message:

{ code: -32602, message: '"Invalid Policy ID. Please ensure you're sending requests with the api key associated with the policy's app, and that the policy is active."' }

Solution

Gas manager policies can only be tied to one app and one chain. To resolve this issue:

• Use both the policy ID and the API key associated with the app for which the Gas Manager policy is configured

• Policies can only be configured for one chain at a time

• Ensure the policy is active

Policy Limit Errors

Below are errors associated with Gas Manager policy limits.

Policy's max spend per spender exceeded.

This error indicates that the total amount sponsored for this sender has reached the maximum limit set in the policy. Review your policy and adjust the max spend per address if needed.

Policy's max count per spender exceeded.

This error means that you've sponsored the max number of userOps for this sender, as specified in the Gas Manager policy. Review your policy and adjust the max operations per address if needed.

Policy max count exceeded.

This error means that you've sponsored the max number of userOps for this policy. Review your policy and adjust the max operations per policy if needed.

Policy max count exceeded.

This error means that you've reached the maximum dollar amount for this policy. Review your policy and adjust the max spend per policy if needed.

User operation cost exceeds specified spend limit

This error means that the gas required for this userOp exceeds the max dollar amount you are willing to sponsor per userOp, as specified in the Gas Manager policy. Adjust the max spend per UO in your policy if needed.

This can happen intermittently even after raising the per-UO limit, when network gas fees spike or transaction activity increases on the chain your policy covers. The check runs against current network conditions, so set your max spend per UO with headroom for periods of high activity rather than your typical cost, or add fallback logic that lets the user cover gas themselves when the cost exceeds the amount you want to sponsor.

sender isn't in policy's allowlist

If the allowlist is not empty, only sender addresses included in the allowlist can be sponsored. Add the sender address to the allowlist if sponsorship is desired.

sender address in policy's blocklist

Any address included in the blocklist is banned from receiving sponsorship. Remove the sender address from the blocklist if sponsorship is desired.

policy hasn't started

This error means the policy is not currently active because it has not started. Check the policy's start date.

policy has ended

This error means the policy is not currently active because it has ended. Check the policy's end date.

Team Sponsorship Limit Errors

Example error message:

This transaction's USD cost will put your team over your gas sponsorship Limit. To increase your limit, please upgrade your account, buy gas credits in your Gas Manager Dashboard: <https://dashboard.alchemy.com/gas-manager>, or reach out to [account-abstraction@alchemy.com](<mailto:account-abstraction@alchemy.com>).

This error means that this userOp will cause you to exceed your sponsorship limit. This limit is determined by your Alchemy tier (see limits here) and is checked against the sum of pending and mined User Operations.

• We offer free unlimited sponsorship on testnets

• Your usage limit is a running total that does not automatically reset every month

Any unpaid Gas Manager invoices from previous billing periods carry over and count against this limit alongside the current period's usage, so the total does not reset on a fixed monthly schedule. In the Gas Manager Dashboard, this shows as an orange bar for the carried-over unpaid balance next to the blue bar for your fresh monthly limit. Once all outstanding invoices are paid, the orange bar disappears and your usage returns to the fresh monthly limit.

Why do pending UOs count towards my limit?

Any valid paymaster signature will count towards this limit as these signatures could be used for sponsorship.

• Paymaster signatures are valid for the policy expiry time defined on the policy itself.

• Setting your policy expiry too long could cause the number of valid signatures to pile up. Even if those user operations are rejected at the Bundler level on send user operation, the paymaster signature will continue to be valid and count towards your limit until the signature expires on-chain. There is no way to invalidate this signature once it has been granted.

Will I get alerted when I get close to this limit?

Yes! Billing admin on your team account will be emailed when you are at 50%, 75%, 90%, and 100% of your limit.

Solutions

1. Upgrade your Alchemy plan - see limits here

2. Purchase gas credits - in your gas manager dashboard you can purchase gas credits in USD to increase your limit. Check out a demo here.

   • These credits are a one-time, non-refundable purchase applied to your gas manager bill at the end of the month

   • Your limit will be the sum of your tier limit plus any unused purchased gas credits

Sponsorship Blocked Right After Switching to Pay As You Go

When your team upgrades to Pay As You Go, Alchemy sets your sponsored-gas spend limit to $0 by default. Until that limit is raised, Gas Manager policy creation and sponsorship are blocked, even though the plan upgrade itself completed successfully.

Adding a payment method only enables Pay As You Go billing. It does not raise this limit.

Solution

Go to your Gas Manager Dashboard and set a monthly sponsored-gas spend limit above $0. This lifts the block and allows policy creation and sponsorship to proceed.

Pending Sponsorship Limit Errors

Here is an example error message:

This transaction's worst-case sponsorship cost ($X) plus your team's current pending sponsorship spend ($Y) exceeds your pending sponsorship limit ($50.00). This is a separate, in-flight limit and does not mean you have reached your overall gas sponsorship limit.

What is this?

This is a separate guardrail from your overall gas sponsorship limit — it caps the total worst-case cost of your team's currently pending (not yet mined) sponsored user operations at any given time. It's designed to bound risk from in-flight sponsorship during bursts of activity.

The cap amount depends on your plan tier:

The worst-case cost for a transaction is calculated from the fee and gas parameters set on that transaction (gas limit, maxFeePerGas, and maxPriorityFeePerGas), not from the transaction's actual expected on-chain cost. Conservatively high gas parameters inflate this worst-case estimate even when the transaction is unlikely to actually cost that much — in practice this worst-case figure commonly runs around double the transaction's actual on-chain cost.

Important: topping up your overall gas sponsorship balance or purchasing gas credits does not raise this limit — it is a separate cap with no current self-serve configuration option.

Solution

Try lowering the gas limit, maxFeePerGas, or maxPriorityFeePerGas on the transaction, or rely on Alchemy's provided gas estimates instead of setting conservatively high values. Lowering these inputs reduces the worst-case sponsorship estimate and may bring the transaction back under the pending limit.

Note that this change only affects new transactions going forward. A transaction already counted against the pending limit stays counted until it mines or its paymaster signature expires — shortening the signature expiry window reduces how long future transactions stay pending, but won't immediately clear a limit that's already been hit by transactions sent before the change.

If you're hitting this limit during a high-volume event (e.g. a token launch or live drop), or lowering the gas parameters doesn't resolve it, contact support@alchemy.com so the team can review whether a higher pending limit can be set for your account.

Solana Fee Payer Errors

Example error message:

{ "jsonrpc": "2.0", "error": { "code": -32602, "message": "Gas sponsorship on SOLANA_MAINNET is not enabled for your team. Please reach out to support@alchemy.com to be added to the allowlist" }, "id": 1 }

Solution

This error appears when calling alchemy_requestFeePayer to sponsor gas on Solana. Solana gas sponsorship is available on the Enterprise plan only, with no self-serve allowlisting path for other plan tiers. If your team is not on Enterprise, this call returns this error regardless of your policy configuration.

To use Solana gas sponsorship, contact our sales team about upgrading to Enterprise.

Example error message:

{"jsonrpc":"2.0","id":1,"error":{"code":-32602,"message":"Unable to estimate fee for transaction"}}

Solution

This error appears when calling alchemy_requestFeePayer and the paymaster's internal getFeeForMessage call returns a null fee. The Solana node returns null for the fee when the transaction has an expired or invalid blockhash (including a placeholder value used in place of a real one) or a message it can't parse.

If you fetch the blockhash yourself before calling alchemy_requestFeePayer, request it with finalized commitment rather than confirmed. The paymaster's getFeeForMessage call defaults to finalized commitment, so a confirmed blockhash from a slot that hasn't finalized yet can intermittently return null and produce this error. Refreshing the blockhash and retrying with finalized commitment resolves the issue in most cases.

Note: the serializedTransaction shown in Dashboard request logs is truncated. Replaying that truncated value in the Sandbox will produce different, misleading errors rather than reproducing the original issue.

Related docs

• alchemy_requestFeePayer