Skip to content
Alchemy Logo

Bundler RPC Errors

Learn about the different Bundler error codes.

This document provides a list of the JSON-RPC errors that you might encounter when using the Bundler API. These are in addition to the standard JSON-RPC error codes returned by a bad method call.

Field names below reflect what the Alchemy bundler (Rundler) actually serializes. If a code is emitted without a data object, the useful context is included in the top-level message string instead.

  • Description: The userOp is rejected by entryPoint's simulateValidation, during account creation or validation. The -32500 error code may be accompanied by an additional AAxx revert code provided by the EntryPoint to give additional guidance.

Data Fields:

  • reason: Optional string providing the main reason for the rejection.
  • innerReason: Optional string providing additional details for the rejection.
  • revertData: Optional bytes containing additional data related to the rejection.

  • Description: The userOp is rejected by paymaster's validatePaymasterUserOp. The paymaster's rejection reason is included in the top-level message field of the error.

Data Fields:

  • paymaster: Address of the paymaster that rejected the operation.

  • Description: The userOp does an Opcode violation or tries to access inaccessible storage. Before submitting userOps, bundlers must make sure userOps don't grief the bundler by accessing banned opcodes when checking a signature.

Data Fields:

For most opcode violations, no additional data fields are returned. The offending entity type and opcode are included in the top-level message string.

When the violation is caused by an entity (or a dependency) with insufficient stake, the following fields are additionally returned:

  • needsStake: Single-key object identifying the entity that needs staking, in the form {<entityType>: <address>} where <entityType> is one of account, paymaster, factory, or aggregator.
  • accessingEntity: Type of entity accessing the storage.
  • accessedAddress: Address of the accessed storage.
  • accessedEntity: Optional type of accessed entity.
  • slot: Storage slot accessed.
  • minimumStake: Minimum required stake.
  • minimumUnstakeDelay: Minimum required unstake delay.

  • Description: Either the account or the paymaster returned a time-range, and it is already expired or will expire soon.

Data Fields:

  • validUntil: Timestamp indicating the valid until time.
  • validAfter: Timestamp indicating the valid after time.
  • paymaster: Optional address of the paymaster.

  • Description: The userOp was rejected because the paymaster or aggregator is throttled or banned.

Data Fields:

The data value is a single-key object identifying the throttled or banned entity, in the form {<entityType>: <address>} where <entityType> is one of account, paymaster, factory, or aggregator.

Example: {"paymaster": "0x1234...5678"}.

  • Description: The userOp was rejected because either the paymaster's or aggregator's stake or unstake delay was too low, or the sender has too many pending operations for an unstaked account. Details on which entity needs staking are included in the top-level message field.

Data Fields:

  • No additional data fields.

  • Description: The userOp was rejected because the smart account specified unsupported signature aggregator.

Data Fields:

  • aggregator: Address of the unsupported aggregator.

  • Description: The userOp was rejected because it contains an invalid signature from the sender or the paymaster.

Data Fields:

  • No additional data fields.

  • Description: The userOp was rejected because the paymaster's deposit on the EntryPoint is insufficient to cover the maximum gas cost of the operation. The required and current balances are included in the top-level message field.

Data Fields:

  • No additional data fields.

  • Description: The userOp was reverted during the execution phase.

Data Fields:

  • revertData: Bytes containing additional data related to the revert. Only present when the revert included return data; text-only reverts include the revert reason in the top-level message field and do not populate the data object.

  • Description: The userOp struct/fields sent to the bundler were invalid.

Data Fields:

Most -32602 responses have no data object. For the specific "replacement underpriced" case (a resubmitted userOp whose fees don't meet the required replacement bump), data includes:

  • currentMaxPriorityFee: Current maximum priority fee for the pending userOp being replaced.
  • currentMaxFee: Current maximum fee for the pending userOp being replaced.

Description: Internal JSON-RPC error.

Data Fields:

  • No additional data fields.
Was this page helpful?