docs: add error handling and UX guidelines for OnchainKit transactions

[schoolkamsergj]

Summary

Adds a new error-handling.md guide to address the documentation gap raised in #2570.

OnchainKit exposes several user-facing failure modes but there was no centralized guidance on how errors are surfaced or how apps should translate them into clear, user-friendly messages.

What's added

packages/onchainkit/src/transaction/docs/error-handling.md

Based on actual source types:

• TransactionError — { code: string, error: string, message: string }, re-exported from @coinbase/onchainkit/transaction
• LifecycleStatus — union type with statusName: 'error' carrying TransactionError as statusData
• isUserRejectedRequestError() — existing util that checks err.cause.name === 'UserRejectedRequestError'
• SEND_CALLS_NOT_SUPPORTED_ERROR constant from constants.ts

Five error categories covered:

• Wallet not connected — detect with wagmi useAccount(), disable UI before reaching OnchainKit
• Wrong network — detect with wagmi useChainId(), offer switchChain() button; <Transaction chainId={base.id}> guards this automatically
• User rejected — surfaces in TransactionError.message as "User rejected" string (no numeric code on TransactionError)
• Insufficient funds — surfaces in TransactionError.message as "insufficient funds" string, link to <FundButton>
• RPC / network errors — timeout/fetch/network strings in TransactionError.message, exponential backoff recommended

Patterns included:

• classifyTransactionError() — maps TransactionError fields to an ErrorCategory enum via string matching on .message and .error
• USER_MESSAGES lookup table for app-wide consistent copy
• Decision table: when to auto-retry vs. prompt the user vs. stay silent
• Usage examples with real <Transaction onError> and <Transaction onStatus> props

Why this matters

Without this guide, every team building on OnchainKit independently implements error parsing — resulting in inconsistent UX across the Base ecosystem. This centralizes the recommended patterns based on the actual library types.

Fixes #2570

[cb-heimdall]

🟡 Heimdall Review Status

Requirement	Status	More Info
Reviews	🟡 0/1	Denominator calculation Show calculation 1 if user is bot 0 1 if user is external 0 2 if repo is sensitive 0 From .codeflow.yml 1 Additional review requirements Show calculation Max 0 0 From CODEOWNERS 0 Global minimum 0 Max 1 1 1 if commit is unverified 1 Sum 2

[vercel]

@schoolkamsergj is attempting to deploy a commit to the Coinbase Team on Vercel.

A member of the Team first needs to authorize it.