Frontend error handling and user feedback

[codebestia]

Write apps/web/docs/concepts-error-handling.md: how API failures, socket errors, wallet rejections and decryption failures reach the user. Covers lib/useToast.ts, per-route error states, and the socket error event handling.

Acceptance criteria:

• Documents the toast API and when to use it versus inline error state
• Maps backend error responses onto user-facing messages, cross-linking the backend error catalog
• Documents the rule that a decryption failure must never be shown as a generic crash — it has a specific, non-alarming presentation
• Documents retry and offline behaviour, including what happens to an optimistic message when the send ultimately fails

[sahmwelll]

@sahmwelll has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

Why I'd like to work on this issue

Error handling is one of the most important but often overlooked aspects of user experience. When something goes wrong—an API failure, a wallet rejection, or a decryption error—how the app communicates that to the user determines whether they feel frustrated or understood. Without clear documentation, developers might display generic crashes instead of specific, non-alarming messages. A well-documented error handling strategy ensures consistency, empathy, and a better user experience.

I want to write this documentation because it's a foundational piece of developer onboarding and UX consistency. Documenting the toast API, mapping backend errors to user-facing messages, and covering retry and offline behavior will help the team build more resilient and user-friendly applications.

Relevant experience

Written technical documentation for frontend error handling, state management, and API integration.

Built React/Next.js applications with toast notifications, inline error states, and error boundaries.

Familiar with WebSocket error handling, optimistic updates, and offline/retry patterns.

Experience with wallet integration and handling decryption failures gracefully.

My approach

Document toast API – Cover lib/useToast.ts and explain when to use toasts vs inline error states.

Map backend errors – Cross-link backend error catalog with user-facing messages.

Document decryption failures – Explain the rule that they must never appear as generic crashes; always use the specific, non-alarming presentation.

Document retry/offline behavior – Cover optimistic message failure scenarios and what users see.

Review and refine – Ensure the documentation is clear, accurate, and actionable for developers.

I'll deliver a clear, comprehensive error handling guide that improves developer experience and user feedback consistency.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @sahmwelll to this issue.

[G-ELM]

@G-ELM has applied to work on this issue as part of the Stellar Wave Program's 8th wave.

Hello
I can work on this.
Please assign.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @G-ELM to this issue.

[drips-wave]

Congratulations, @G-ELM! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on August 31, 2026.

🧑‍💻 @G-ELM: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊