Errors and retries

All SDK errors extend InkPaymasterError.

Error	Meaning
InkPaymasterValidationError	Local input or remote response failed SDK validation.
InkPaymasterHttpError	The quote or health endpoint returned a non-success HTTP status.
InkPaymasterRpcError	The public bundler returned a JSON-RPC error.

try {
  await bundlerClient.sendUserOperation({calls});
} catch (error) {
  if (error instanceof InkPaymasterHttpError) {
    console.error(error.status, error.body);
  }
}

Retry rules

• Reuse the same idempotency key when retrying the same logical operation.
• After a timeout or ambiguous submission, query the UserOperation receipt before rebuilding it.
• Use exponential backoff with jitter for temporary transport failures, 429, and 503 responses.
• Do not blindly retry validation errors or insufficient balance/allowance failures.
• Create a new operation and idempotency key if any quote-bound field changes.

Common failures

Insufficient USDC or allowance

Call getPublicPaymasterAccountState and confirm both values cover maxTokenCost. Remember that amounts are USDC base units with six decimals.

Unsupported account or EntryPoint

The account, operation encoding, Viem client, paymaster, and bundler must all use EntryPoint v0.7. The SDK rejects v0.6-style initCode operations.

Expired quote

Build a new operation using a new idempotency key. Never attach old paymaster data to a changed or newly signed UserOperation.