Separate HTTP errors, wallet errors and on-chain reverts

A swap can fail before a quote exists, before a wallet signs, during broadcasting or after on-chain execution. Store the failure stage with its cause so the recovery action matches the evidence.

The wallet provider standard defines errors such as user rejection and disconnection. Provider APIs add their own domains: 0x distinguishes request errors from quote issues. Preserve both levels rather than overwriting everything with a single message string.

Design a stable internal error object

A proposed object includes stage, class, provider, retryable policy, safe user message and correlation ID. Keep raw upstream detail in a restricted diagnostic path only when it is safe to retain. The user should see what they can do next, not an unfiltered stack trace.

Do not decide retryability from English text matching alone. Upstream wording can change. Use documented codes where available, with an explicit unknown-code branch.

Measure failure rates by stage. A high wallet-rejection rate may reflect users declining terms, while a high simulation-revert rate suggests an integration or market-state issue. Combining them hides both patterns.

Test each boundary independently and verify that the application never reports funds lost merely because an HTTP request failed. Conversely, a mined failed receipt should not be disguised as a harmless network retry.