Errors and retries

Errors from the low-level prepaid client 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.

The sponsored client is a standard Viem PaymasterClient, so transport, HTTP, and ERC-7677 JSON-RPC failures use Viem's error types. In particular, 401 means the bearer key is missing, invalid, disabled, or not enabled for sponsorship. Do not log the request headers while handling it.

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.
• The sponsored client retries transport failures up to twice by default; configure retryCount when a different backend policy is required.
• 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 reimbursement token or allowance

Call getPublicPaymasterAccountState and confirm both values cover maxTokenCost. Remember that amounts use the selected token's base units. USDC, USD₮0, and USDG currently use 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.